الاسم¶

read - قراءة من واصف ملف

المكتبة¶

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

موجز¶

#include <unistd.h>

ssize_t read(size_t count;
             int fd, void buf[count], size_t count);

الوصف¶

read() تحاول قراءة حتى count بايت من واصف الملف fd إلى المخزن المؤقت الذي يبدأ عند buf.

في الملفات التي تدعم البحث، تبدأ عملية القراءة عند إزاحة الملف، وتُزاد إزاحة الملف بعدد البايتات المقروءة. إذا كانت إزاحة الملف عند نهاية الملف أو بعدها، لا تُقرأ أي بايتات، وتُرجع read() صفرًا.

إذا كان count صفرًا، read() قد تكتشف الأخطاء الموصوفة أدناه. في غياب أي أخطاء، أو إذا لم تتحقق read() من الأخطاء، فإن read() مع count بقيمة 0 تُرجع صفرًا وليس لها تأثيرات أخرى.

وفقًا لـ POSIX.1، إذا كانت count أكبر من SSIZE_MAX، فإن النتيجة تكون محددة بواسطة التنفيذ؛ انظر «ملاحظات» للحد الأقصى في لينكس.

قيمة الإرجاع¶

عند النجاح، يُرجع عدد البايتات المقروءة (الصفر يشير إلى نهاية الملف)، ويُقدم موضع الملف بهذا العدد. ليس خطأً إذا كان هذا العدد أصغر من عدد البايتات المطلوبة؛ قد يحدث هذا مثلاً لأن بايتات أقل متاحة فعليًا الآن (ربما لأننا كنا قريبين من نهاية الملف، أو لأننا نقرأ من أنبوب، أو من طرفية)، أو لأن read() قُطعت بإشارة. انظر أيضًا NOTES.

عند الخطأ، يُرجع -1، ويُضبط errno للإشارة إلى الخطأ. في هذه الحالة، يُترك غير محدد ما إذا كان موضع الملف (إن وجد) يتغير.

الأخطاء¶

EAGAIN

يشير واصف الملف fd إلى ملف غير مقبس وقد وُسم بغير مانع (O_NONBLOCK)، وستحجب القراءة. انظر open(2) لمزيد من التفاصيل حول العلم O_NONBLOCK.

EAGAIN أو EWOULDBLOCK

يشير واصف الملف fd إلى مقبس وقد وُسم بغير مانع (O_NONBLOCK)، وستحجب القراءة. يسمح POSIX.1-2001 بإرجاع أي من الخطأين لهذه الحالة، ولا يتطلب أن تكون هذه الثوابت بنفس القيمة، لذا يجب على تطبيق محمول التحقق من كلا الاحتمالين.

EBADF

fd ليس واصف ملف صالحًا أو ليس مفتوحًا للقراءة.

EFAULT

buf خارج مساحة العنوان التي يمكنك الوصول إليها.

EINTR

قُطعت الاستدعاء بإشارة قبل قراءة أي بيانات؛ انظر signal(7).

EINVAL

fd مُرفق بكائن غير مناسب للقراءة؛ أو فُتح الملف بالعلم O_DIRECT، وإما العنوان المحدد في buf، أو القيمة المحددة في count، أو إزاحة الملف غير محاذية بشكل مناسب.

EINVAL

أُنشئ fd عبر استدعاء لـ timerfd_create(2) وأُعطي مخزن مؤقت بحجم خاطئ لـ read()؛ انظر timerfd_create(2) لمزيد من المعلومات.

EIO

خطأ I/O. سيحدث هذا مثلاً عندما تكون العملية في مجموعة عمليات خلفية، وتحاول القراءة من طرفيتها المسيطرة، وإما تتجاهل أو تحجب SIGTTIN أو أن مجموعتها العملياتية يتيمة. قد يحدث أيضًا عندما يكون هناك خطأ I/O منخفض المستوى أثناء القراءة من قرص أو شريط. سبب محتمل آخر لـ EIO على أنظمة الملفات الشبكية هو عندما أُخذ قفل استشاري على واصف الملف وفُقد هذا القفل. انظر قسم Lost locks من fcntl(2) لمزيد من التفاصيل.

EISDIR

fd يشير إلى دليل.

قد تحدث أخطاء أخرى، اعتمادًا على الكائن المتصل بـ fd.

المعايير¶

POSIX.1-2008.

التاريخ¶

SVr4، 4.3BSD، POSIX.1-2001.

ملاحظات¶

في لينكس، read() (واستدعاءات نظام مشابهة) ستنقل على الأكثر 0x7ffff000 (2,147,479,552) بايت، مع إرجاع عدد البايتات المنقولة فعليًا. (هذا صحيح على كل من الأنظمة 32-bit و64-bit.)

في أنظمة ملفات NFS، قراءة كميات صغيرة من البيانات ستحدث الطابع الزمني فقط في المرة الأولى، وقد لا تفعل الاستدعاءات اللاحقة ذلك. هذا ناتج عن تخزين سمات جانب العميل مؤقتًا، لأن معظم إن لم يكن كل عملاء NFS يتركون تحديثات st_atime (وقت آخر وصول للملف) للخادم، والقراءات من جانب العميل المُرضاة من خبيئة العميل لن تسبب تحديثات st_atime على الخادم حيث لا توجد قراءات من جانب الخادم. يمكن الحصول على دلالات UNIX بتعطيل تخزين سمات جانب العميل مؤقتًا، لكن في معظم الحالات سيزيد هذا بشكل كبير من حمل الخادم ويقلل الأداء.

العلل¶

وفقًا لـ POSIX.1-2008/SUSv4 القسم XSI 2.9.7 («تفاعلات الخيوط مع عمليات الملفات العادية»):

من بين واجهات برمجة التطبيقات المدرجة لاحقًا read() وreadv(2). ومن بين التأثيرات التي يجب أن تكون ذرية عبر الخيوط (والعمليات) هي تحديثات إزاحة الملف. ومع ذلك، قبل لينكس 3.14، لم يكن هذا هو الحال: إذا قامت عمليتان تشاركان وصف ملف مفتوح (انظر open(2)) بتنفيذ read() (أو readv(2)) في نفس الوقت، فإن عمليات I/O لم تكن ذرية فيما يتعلق بتحديث إزاحة الملف، مما أدى إلى أن القراءات في العمليتين قد تتداخل (بشكل غير صحيح) في كتل البيانات التي حصلتا عليها. تم إصلاح هذه المشكلة في لينكس 3.14.

انظر أيضًا¶

close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2), readlink(2), readv(2), select(2), write(2), fread(3)

ترجمة¶

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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