fopen(3)

الاسم
fopen, fdopen, freopen - دوال فتح الدفق

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

موجز
#include <stdio.h>

FILE *fopen(const char *restrict path, const char *restrict mode);
FILE *fdopen(int fd, const char *mode);
FILE *freopen(const char *restrict path, const char *restrict mode,
              FILE *restrict stream);

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

fdopen():
    _POSIX_C_SOURCE

الوصف
تفتح الدالة fopen() الملف الذي اسمه هو سلسلة المحارف المشار إليها بواسطة path وتربط معه تدفقًا.

يشير المعامل mode إلى سلسلة محارف تبدأ بأحد التسلسلات التالية (قد تتبعها محارف إضافية، كما هو موضح أدناه):

r   فتح ملف نصي للقراءة. يُوضع الدفق في بداية الملف.

r+  فتح للقراءة والكتابة. يُوضع الدفق في بداية الملف.

w   اقتطاع الملف إلى طول صفري أو إنشاء ملف نصي للكتابة. يُوضع الدفق في بداية الملف.

w+  فتح للقراءة والكتابة. يُنشأ الملف إذا لم يكن موجودًا، وإلا يُقتطع. يُوضع الدفق في بداية الملف.

a   فتح للإلحاق (الكتابة في نهاية الملف). يُنشأ الملف إذا لم يكن موجودًا. يُوضع الدفق في نهاية الملف.

a+  فتح للقراءة والإلحاق (الكتابة في نهاية الملف). يُنشأ الملف إذا لم يكن موجودًا. يُلحق المخرجات دائمًا بنهاية الملف. لا يحدد POSIX موضع القراءة المبدئي عند استخدام هذا الوضع. بالنسبة لـ glibc، موضع الملف المبدئي للقراءة هو بداية الملف، ولكن بالنسبة لـ Android/BSD/MacOS، موضع الملف المبدئي للقراءة هو نهاية الملف.

يمكن أن تتضمن سلسلة المحارف mode الحرف 'b' إما كآخر حرف أو كحرف بين الأحرف في أي من سلاسل المحارف ذات الحرفين الموصوفة أعلاه. هذا فقط للتوافق مع ISO C وليس له أي تأثير؛ يُتجاهل 'b' في جميع الأنظمة المتوافقة مع POSIX، بما في ذلك Linux. (قد تعالج الأنظمة الأخرى الملفات النصية والملفات الثنائية بشكل مختلف، وقد تكون إضافة 'b' فكرة جيدة إذا كنت تقوم بالإدخال/الإخراج إلى ملف ثنائي وتتوقع أن يُنقل برنامجك إلى بيئات غير UNIX.)

انظر الملاحظات أدناه لتفاصيل إضافات glibc لـ mode.

سيكون لأي ملف منشأ الوضع S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666)، كما يُعدل بقيمة umask للعملية (انظر umask(2)).

قد تُخلط القراءات والكتابات على تدفقات القراءة/الكتابة بأي ترتيب. لاحظ أن ANSI C يتطلب أن تتدخل دالة تحديد موضع الملف بين الإخراج والإدخال، إلا إذا واجهت عملية إدخال نهاية الملف. (إذا لم يُستوف هذا الشرط، يُسمح للقراءة بإرجاع نتيجة كتابات غير الأحدث.) لذلك من الممارسة الجيدة (وأحيانًا ضرورية تحت Linux) وضع عملية fseek(3) أو fsetpos(3) بين عمليات الكتابة والقراءة على مثل هذا الدفق. قد تكون هذه العملية بلا تأثير ظاهريًا (كما في fseek(..., 0L, SEEK_CUR) المُستدعاة لتأثيرها الجانبي المتزامن).

يؤدي فتح ملف في وضع الإلحاق (a كأول حرف من mode) إلى حدوث جميع عمليات الكتابة اللاحقة لهذا الدفق في نهاية الملف، كما لو سبقها الاستدعاء:

    fseek(stream, 0, SEEK_END);

يُفتح واصف الملف المرتبط بالدفق كما لو كان باستدعاء open(2) مع الأعلام التالية:
    نمط fopen() | أعلام open()
    r | O_RDONLY
    w | O_WRONLY | O_CREAT | O_TRUNC
    a | O_WRONLY | O_CREAT | O_APPEND
    r+ | O_RDWR
    w+ | O_RDWR | O_CREAT | O_TRUNC
    a+ | O_RDWR | O_CREAT | O_APPEND

  fdopen()
تربط الدالة fdopen() دفقًا بوصف الملف الموجود، fd. يجب أن يكون نمط الدفق (أحد القيم "r", "r+", "w", "w+", "a", "a+") متوافقًا مع نمط وصف الملف. يُضبط مؤشر موضع الملف للدفق الجديد على ذلك الذي ينتمي إلى fd، وتُمسح مؤشرات الخطأ ونهاية الملف. لا تسبب الأنماط "w" أو "w+" اقتطاع الملف. لا يُنسخ وصف الملف، وسيُغلق عند إغلاق الدفق المنشأ بواسطة fdopen(). نتيجة تطبيق fdopen() على كائن ذاكرة مشتركة غير محددة.

  freopen()
تفتح الدالة freopen() الملف الذي اسمه سلسلة المحارف المشار إليها بواسطة path وتربط الدفق المشار إليه بواسطة stream به. يُغلق الدفق الأصلي (إن وُجد). يُستخدم معامل نمط تمامًا كما في الدالة fopen().

إذا كان path مؤشرًا فارغًا، تغير freopen() نمط الدفق إلى ذلك المحدد في نمط؛ أي تعيد freopen() فتح اسم المسار المرتبط بالدفق. أُضيفت مواصفات هذا السلوك في معيار C99، الذي ينص:

    في هذه الحالة، لا يلزم إغلاق وصف الملف المرتبط بالدفق إذا نجحت استدعاء freopen(). يُعرّف حسب التنفيذ أي تغييرات النمط مسموح بها (إن وُجدت)، وتحت أي ظروف.

الاستخدام الرئيسي للدالة freopen() هو تغيير الملف المرتبط بدفق نصي قياسي (stderr، stdin، أو stdout).

قيمة الإرجاع
عند الإكمال بنجاح، تُرجع fopen()، fdopen()، و freopen() مؤشر FILE. وإلا، يُرجع NULL ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EINVAL
    كان نمط المقدم إلى fopen()، fdopen()، أو freopen() غير صالح.

قد تفشل الدوال fopen() و fdopen() و freopen() أيضًا وتُعيِّن errno لأي من الأخطاء المحددة للروتين malloc(3).

قد تفشل الدالة fopen() أيضًا وتُعيِّن errno لأي من الأخطاء المحددة للروتين open(2).

قد تفشل الدالة fdopen() أيضًا وتُعيِّن errno لأي من الأخطاء المحددة للروتين fcntl(2).

قد تفشل الدالة freopen() أيضًا وتُعيِّن errno لأي من الأخطاء المحددة للروتينات open(2) و fclose(3) و fflush(3).

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
fopen()، fdopen()، freopen() | سلامة الخيوط | MT-Safe

المعايير

fopen()
freopen()
    C11, POSIX.1-2008.

fdopen()
    POSIX.1-2008.

التاريخ

fopen()
freopen()
    POSIX.1-2001، C89.

fdopen()
    POSIX.1-2001.

ملاحظات

  ملاحظات glibc
تسمح مكتبة C لجنو بالامتدادات التالية للسلسلة المحارف المحددة في mode:

c (منذ glibc 2.3.3)
    لا تجعل عملية الفتح، أو عمليات القراءة والكتابة اللاحقة، نقاط إلغاء خيط. يُتجاهل هذا العلم لـ fdopen().

e (منذ glibc 2.7)
    افتح الملف بالعلم O_CLOEXEC. انظر open(2) لمزيد من المعلومات. يُتجاهل هذا العلم لـ fdopen().

m (منذ glibc 2.3)
    حاول الوصول إلى الملف باستخدام mmap(2)، بدلاً من استدعاءات النظام للإدخال/الإخراج (read(2)، write(2)). حاليًا، يُحاول استخدام mmap(2) فقط لملف مفتوح للقراءة.

x   افتح الملف حصريًا (مثل العلم O_EXCL لـ open(2)). إذا كان الملف موجودًا بالفعل، تفشل fopen() وتُعيِّن errno إلى EEXIST. يُتجاهل هذا العلم لـ fdopen().

بالإضافة إلى المحارف أعلاه، تدعم fopen() و freopen() الصياغة التالية في mode:

,ccs=string

يُؤخذ string المُعطى كاسم لمجموعة محارف مُعمَّاة ويُوسم الدفق كموجه عريض. بعد ذلك، تُحوِّل دوال التحويل الداخلية الإدخال/الإخراج من وإلى مجموعة المحارف string. إذا لم تُحدد صياغة ,ccs=string، فتُحدد التوجيه العريض للتدفق بواسطة أول عملية ملف. إذا كانت تلك العملية عملية محرف عريض، يُوسم الدفق كموجه عريض، وتُحمَّل دوال للتحويل إلى مجموعة المحارف المُعمَّاة.

العلل
عند تحليل محارف العلم الفردية في mode (أي المحارف التي تسبق تحديد "ccs")، يُحدد تنفيذ glibc لـ fopen() و freopen() عدد المحارف المفحوصة في mode إلى 7 (أو، قبل glibc 2.14، إلى 6، وهو ما لم يكن كافيًا لتضمين تحديدات محتملة مثل "rb+cmxe"). يُحلل التنفيذ الحالي لـ fdopen() على الأكثر 5 محارف في mode.

انظر أيضًا
open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3), open_memstream(3)

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

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

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