getcwd(3)

الاسم
getcwd, getwd, get_current_dir_name - الحصول على دليل العمل الحالي

المكتبة
مكتبة سي المعيارية (libc، -lc)

موجز
#include <unistd.h>

char *getcwd(size_t size;
             char buf[size], size_t size);
char *get_current_dir_name(void);

[[مهمل]] char *getwd(char buf[PATH_MAX]);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

get_current_dir_name():
    _GNU_SOURCE

getwd():
    منذ glibc 2.12:
        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
            || /* glibc <= 2.19: */ _BSD_SOURCE
    قبل glibc 2.12:
        _BSD_SOURCE || _XOPEN_SOURCE >= 500

الوصف
ترجع هذه الدوال سلسلة محارف منتهية بقيمة خالية تحتوي على اسم مسار مطلق هو دليل العمل الحالي للعملية المستدعية. يُرجع اسم المسار كنتيجة للدالة وعبر المعامل buf، إن وُجد.

تنسخ الدالة getcwd() اسم مسار مطلق لدليل العمل الحالي إلى المصفوفة المشار إليها بواسطة buf، والتي طولها size.

إذا تجاوز طول اسم المسار المطلق لدليل العمل الحالي، بما في ذلك البايت الختامي الخالي، size بايت، يُرجع NULL، ويُضبط errno على ERANGE؛ يجب على التطبيق التحقق من هذا الخطأ، وتخصيص مخزن مؤقت أكبر إذا لزم الأمر.

كإضافة لمعيار POSIX.1-2001، تخصص دالة getcwd() الخاصة بـ glibc المخزن المؤقت ديناميكيًا باستخدام malloc(3) إذا كان buf NULL. في هذه الحالة، يكون للمخزن المؤقت المخصص الطول size ما لم يكن size صفرًا، حيث يُخصص buf بالحجم اللازم. يجب على المستدعي تحرير المخزن المؤقت المُعاد باستخدام free(3).

ستخصص get_current_dir_name() باستخدام malloc(3) مصفوفة كبيرة بما يكفي لاحتواء اسم المسار المطلق لدليل العمل الحالي. إذا كان المتغير البيئي PWD مضبوطًا، وقيمته صحيحة، فستُعاد تلك القيمة. يجب على المستدعي تحرير المخزن المؤقت المُعاد باستخدام free(3).

لا تخصص getwd() أي ذاكرة باستخدام malloc(3). يجب أن يكون المعامل buf مؤشرًا إلى مصفوفة طولها PATH_MAX بايت على الأقل. إذا تجاوز طول اسم المسار المطلق لدليل العمل الحالي، بما في ذلك البايت الختامي الخالي، PATH_MAX بايت، يُرجع NULL، ويُضبط errno على ENAMETOOLONG. (لاحظ أنه في بعض الأنظمة، قد لا يكون PATH_MAX ثابتًا في وقت الترجمة؛ علاوة على ذلك، قد تعتمد قيمته على نظام الملفات، انظر pathconf(3).) لأسباب تتعلق بقابلية النقل والأمان، يُهمل استخدام getwd().

قيمة الإرجاع
عند النجاح، ترجع هذه الدوال مؤشرًا إلى سلسلة محارف تحتوي على اسم مسار دليل العمل الحالي. في حالة getcwd() و getwd()، هذه هي نفس قيمة buf.

عند الفشل، ترجع هذه الدوال NULL، ويُضبط errno للإشارة إلى الخطأ. محتويات المصفوفة المشار إليها بواسطة buf غير محددة عند الخطأ.

الأخطاء

EACCES
    رُفض الإذن لقراءة أو البحث في مكون من اسم الملف.

EFAULT
    يشير buf إلى عنوان سيئ.

EINVAL
    المعامل size هو صفر و buf ليس مؤشرًا خاليًا.

EINVAL
    getwd(): buf هو NULL.

ENAMETOOLONG
    getwd(): حجم سلسلة محارف اسم المسار المطلق المنتهية بقيمة خالية يتجاوز PATH_MAX بايت.

ENOENT
    فُصل دليل العمل الحالي.

ENOMEM
    نفدت الذاكرة.

ERANGE
    المعامل size أقل من طول اسم المسار المطلق لدليل العمل، بما في ذلك البايت الختامي الخالي. تحتاج إلى تخصيص مصفوفة أكبر والمحاولة مرة أخرى.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
getcwd(), getwd() | سلامة الخيوط | MT-Safe
get_current_dir_name() | سلامة الخيوط | بيئة آمنة لتعدد الخيوط (MT-Safe)

الإصدارات
يترك POSIX.1-2001 سلوك getcwd() غير محدد إذا كان buf هو NULL.

لا يُعرّف POSIX.1-2001 أي أخطاء لـ getwd().

الإصدارات

  الاختلافات بين مكتبة C والنواة
في لينكس، يوفر النواة استدعاء نظام getcwd() والذي ستستخدمه الدوال الموصوفة في هذه الصفحة إن أمكن. يأخذ استدعاء النظام نفس الوسائط مثل دالة المكتبة التي تحمل نفس الاسم، ولكنه مقيد بإرجاع بحد أقصى PATH_MAX بايت. (قبل لينكس 3.12، كان الحد الأقصى لحجم اسم المسار المُعاد هو حجم صفحة النظام. في العديد من البنى، يكون كل من PATH_MAX وحجم صفحة النظام 4096 بايت، ولكن بعض البنى لها حجم صفحة أكبر.) إذا تجاوز طول اسم مسار دليل العمل الحالي هذا الحد، فإن استدعاء النظام يفشل مع الخطأ ENAMETOOLONG. في هذه الحالة، تعود دوال المكتبة إلى تنفيذ بديل (أبطأ) يُرجع اسم المسار الكامل.

بعد تغيير في لينكس 2.6.36، ستُسبق اسم المسار المُعاد من استدعاء النظام getcwd() بالسلسلة "(unreachable)" إذا لم يكن الدليل الحالي أسفل الدليل الجذر للعملية الحالية (على سبيل المثال، لأن العملية عيّنت جذر نظام ملفات جديد باستخدام chroot(2) دون تغيير دليلها الحالي إلى الجذر الجديد). يمكن أيضًا أن يحدث هذا السلوك بواسطة مستخدم غير مميز عن طريق تغيير الدليل الحالي إلى مساحة وصل أخرى. عند التعامل مع أسماء المسارات من مصادر غير موثوقة، يجب على مستدعي الدوال الموصوفة في هذه الصفحة (قبل glibc 2.27) أو استدعاء النظام الخام getcwd() النظر في التحقق مما إذا كان اسم المسار المُعاد يبدأ بـ '/' أو '(' لتجنب تفسير مسار غير قابل للوصول بشكل خاطئ كاسم مسار نسبي.

المعايير

getcwd()
    POSIX.1-2008.

get_current_dir_name()
    GNU.

getwd()
    لا شيء.

التاريخ

getcwd()
    POSIX.1-2001.

getwd()
    POSIX.1-2001، ولكن مُوسوم بـ LEGACY. أُزيل في POSIX.1-2008. استخدم getcwd() بدلاً من ذلك.

تحت لينكس، تستخدم هذه الدوال استدعاء النظام getcwd() (المتوفر منذ لينكس 2.1.92). في الأنظمة الأقدم، كانت تستعلم عن /proc/self/cwd. إذا كان كل من استدعاء النظام ونظام ملفات proc مفقودين، يُستدعى تنفيذ عام. فقط في هذه الحالة يمكن أن تفشل هذه الاستدعاءات تحت لينكس مع EACCES.

ملاحظات
غالبًا ما تُستخدم هذه الدوال لحفظ موقع دليل العمل الحالي بهدف العودة إليه لاحقًا. فتح الدليل الحالي (".") واستدعاء fchdir(2) للعودة هو عادةً بديل أسرع وأكثر موثوقية عندما تتوفر واصفات ملفات كافية، خاصة على المنصات غير لينكس.

العلل
منذ تغيير لينكس 2.6.36 الذي أضاف "(unreachable)" في الظروف الموصوفة أعلاه، فشل تنفيذ glibc لـ getcwd() في الامتثال لـ POSIX وأعاد اسم مسار نسبي عندما يتطلب عقد API اسم مسار مطلق. مع glibc 2.27 فصاعدًا، تم تصحيح هذا؛ استدعاء getcwd() من اسم المسار هذا سيؤدي الآن إلى الفشل مع ENOENT.

انظر أيضًا
pwd(1)، chdir(2)، fchdir(2)، open(2)، unlink(2)، free(3)، malloc(3)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.