الاسم¶

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]);

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).

الإصدارات¶

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

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

الإصدارات¶

المعايير¶

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 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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