fallocate(2)

الاسم
fallocate - معالجة مساحة الملف

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

موجز
#define _GNU_SOURCE             /* See feature_test_macros(7) */
#include <fcntl.h>

int fallocate(int fd, int mode, off_t offset, off_t size);

الوصف
هذه استدعاء نظام غير محمول خاص بلينكس. للحصول على الطريقة المحمولة المحددة بمعيار POSIX.1 لضمان تخصيص مساحة لملف، انظر posix_fallocate(3).

تسمح fallocate() للمستدعي بمعالجة مساحة القرص المخصصة للملف المشار إليه بـ fd مباشرة للنطاق البايتي الذي يبدأ من offset ويستمر لـ size بايت.

تحدد الوسيطة mode العملية التي ستُنفذ على النطاق المعطى. تفاصيل العمليات المدعومة موجودة في الأقسام الفرعية أدناه.

  تخصيص مساحة القرص
العملية المبدئية (أي mode تساوي صفر) لـ fallocate() تخصص مساحة القرص ضمن النطاق المحدد بـ offset و size. سيتغير حجم الملف (كما يبلغ عنه stat(2)) إذا كان offset+size أكبر من حجم الملف. أي منطقة فرعية ضمن النطاق المحدد بـ offset و size لم تحتوِ على بيانات قبل الاستدعاء ستُهيأ إلى صفر. هذا السلوك المبدئي يشبه إلى حد كبير سلوك دالة المكتبة posix_fallocate(3)، وهو مقصود كطريقة لتنفيذ تلك الدالة بشكل أمثل.

بعد استدعاء ناجح، تُضمن عمليات الكتابة اللاحقة في النطاق المحدد بـ offset و size ألا تفشل بسبب نقص مساحة القرص.

إذا حُدد العلم FALLOC_FL_KEEP_SIZE في mode، يكون سلوك الاستدعاء مشابهاً، لكن حجم الملف لن يتغير حتى لو كان offset+size أكبر من حجم الملف. التخصيص المسبق للكتل المصفرة بعد نهاية الملف بهذه الطريقة مفيد لتحسين أعباء عمل الإلحاق.

إذا حُدد العلم FALLOC_FL_UNSHARE_RANGE في mode، ستُجعل امتدادات بيانات الملف المشتركة خاصة بالملف لضمان ألا تفشل كتابة لاحقة بسبب نقص المساحة. عادةً، سيُفعل ذلك بتنفيذ عملية نسخ عند الكتابة على جميع البيانات المشتركة في الملف. قد لا يدعم جميع أنظمة الملفات هذا العلم.

لأن التخصيص يُفعل بقطع بحجم الكتلة، قد تخصص fallocate() نطاقاً أكبر من مساحة القرص مما حُدد.

  إلغاء تخصيص مساحة الملف
تحديد العلم FALLOC_FL_PUNCH_HOLE (متاح منذ لينكس 2.6.38) في mode يلغي تخصيص المساحة (أي ينشئ فجوة) في النطاق البايتي الذي يبدأ من offset ويستمر لـ size بايت. ضمن النطاق المحدد، تُصفر كتل نظام الملفات الجزئية، وتُزال كتل نظام الملفات الكاملة من الملف. بعد استدعاء ناجح، ستعيد القراءات اللاحقة من هذا النطاق أصفاراً.

يجب أن يُجمع العلم FALLOC_FL_PUNCH_HOLE مع FALLOC_FL_KEEP_SIZE في mode بعملية OR؛ بعبارة أخرى، حتى عند ثقب نهاية الملف، لا يتغير حجم الملف (كما يبلغ عنه stat(2)).

لا تدعم جميع أنظمة الملفات FALLOC_FL_PUNCH_HOLE؛ إذا لم يدعم نظام ملفات العملية، يُعاد خطأ. العملية مدعومة على الأقل على أنظمة الملفات التالية:

•   XFS (منذ لينكس 2.6.38)

•   ext4 (منذ لينكس 3.0)

•   Btrfs (منذ لينكس 3.7)

•   tmpfs(5) (منذ لينكس 3.5)

•   gfs2(5) (منذ لينكس 4.16)

  طي مساحة الملف
تحديد العلم FALLOC_FL_COLLAPSE_RANGE (متاح منذ لينكس 3.15) في mode يزيل نطاقاً بايتياً من ملف، دون ترك فجوة. النطاق البايتي الذي سيُطوى يبدأ من offset ويستمر لـ size بايت. عند اكتمال العملية، ستُلحق محتويات الملف التي تبدأ من الموقع offset+size في الموقع offset، وسيصبح الملف أصغر بـ size بايت.

قد يضع نظام الملفات قيوداً على دقة العملية، لضمان تنفيذ فعال. عادةً، يجب أن يكون offset و size مضاعفاً لحجم الكتلة المنطقية لنظام الملفات، الذي يختلف حسب نوع نظام الملفات وتكوينه. إذا كان لنظام الملفات مثل هذا المطلب، تفشل fallocate() بالخطأ EINVAL إذا انتهك هذا المطلب.

إذا وصلت أو تجاوزت المنطقة المحددة بـ offset زائد size نهاية الملف، يُعاد خطأ؛ بدلاً من ذلك، استخدم ftruncate(2) لاقتطاع ملف.

لا يجوز تحديد أعلام أخرى في mode مع FALLOC_FL_COLLAPSE_RANGE.

اعتباراً من لينكس 3.15، FALLOC_FL_COLLAPSE_RANGE مدعوم من ext4 (فقط للملفات القائمة على الامتدادات) و XFS.

  تصفير مساحة الملف
تحديد العلم FALLOC_FL_ZERO_RANGE (متاح منذ لينكس 3.15) في mode يصفر المساحة في النطاق البايتي الذي يبدأ من offset ويستمر لـ size بايت. ضمن النطاق المحدد، تُخصص الكتل مسبقاً للمناطق التي تمتد عبر الفجوات في الملف. بعد استدعاء ناجح، ستعيد القراءات اللاحقة من هذا النطاق أصفاراً.

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

إذا حُدد العلم FALLOC_FL_KEEP_SIZE بالإضافة في mode، يكون سلوك الاستدعاء مشابهاً، لكن حجم الملف لن يتغير حتى لو كان offset+size أكبر من حجم الملف. هذا السلوك هو نفسه عند التخصيص المسبق للمساحة مع تحديد FALLOC_FL_KEEP_SIZE.

لا تدعم جميع أنظمة الملفات FALLOC_FL_ZERO_RANGE؛ إذا لم يدعم نظام ملفات العملية، يُعاد خطأ. العملية مدعومة على الأقل على أنظمة الملفات التالية:

•   XFS (منذ لينكس 3.15)

•   ext4، للملفات القائمة على الامتدادات (منذ لينكس 3.15)

•   SMB3 (منذ لينكس 3.17)

•   Btrfs (منذ لينكس 4.16)

  زيادة مساحة الملف
تحديد العلم FALLOC_FL_INSERT_RANGE (المتوفر منذ لينكس 4.1) في mode يزيد مساحة الملف بإدراج فجوة ضمن حجم الملف دون الكتابة فوق أي بيانات موجودة. ستبدأ الفجوة عند offset وتستمر لـ size بايت. عند إدراج الفجوة داخل الملف، سيتم إزاحة محتويات الملف ابتداءً من offset إلى الأعلى (أي إلى إزاحة ملف أعلى) بمقدار size بايت. إدراج فجوة داخل الملف يزيد حجم الملف بمقدار size بايت.

لهذا الوضع نفس القيود مثل FALLOC_FL_COLLAPSE_RANGE فيما يتعلق بدقة العملية. إذا لم يتم استيفاء متطلبات الدقة، يفشل fallocate() مع الخطأ EINVAL. إذا كانت offset مساوية أو أكبر من نهاية الملف، يتم إرجاع خطأ. لمثل هذه العمليات (أي إدراج فجوة في نهاية الملف)، يجب استخدام ftruncate(2).

لا يمكن تحديد أعلام أخرى في mode بالتزامن مع FALLOC_FL_INSERT_RANGE.

يتطلب FALLOC_FL_INSERT_RANGE دعم نظام الملفات. أنظمة الملفات التي تدعم هذه العملية تشمل XFS (منذ لينكس 4.1) و ext4 (منذ لينكس 4.2).

قيمة الإرجاع
عند النجاح، يُرجع fallocate() صفرًا. عند الخطأ، يُرجع -1 ويتم تعيين errno للإشارة إلى الخطأ.

الأخطاء

EBADF
    fd ليس واصف ملف صالحًا، أو ليس مفتوحًا للكتابة.

EFBIG
    offset+size يتجاوز الحد الأقصى لحجم الملف.

EFBIG
    mode هو FALLOC_FL_INSERT_RANGE، وحجم الملف الحالي+len يتجاوز الحد الأقصى لحجم الملف.

EINTR
    تم التقاط إشارة أثناء التنفيذ؛ انظر signal(7).

EINVAL
    offset كان أقل من 0، أو size كان أقل من أو يساوي 0.

EINVAL
    mode هو FALLOC_FL_COLLAPSE_RANGE والنطاق المحدد بواسطة offset زائد size يصل أو يتجاوز نهاية الملف.

EINVAL
    mode هو FALLOC_FL_INSERT_RANGE والنطاق المحدد بواسطة offset يصل أو يتجاوز نهاية الملف.

EINVAL
    mode هو FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_INSERT_RANGE، ولكن إما offset أو size ليس مضاعفًا لحجم كتلة نظام الملفات.

EINVAL
    mode يحتوي على واحد من FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_INSERT_RANGE وأيضًا أعلام أخرى؛ لا يُسمح بأعلام أخرى مع FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_INSERT_RANGE.

EINVAL
    mode هو FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_ZERO_RANGE أو FALLOC_FL_INSERT_RANGE، ولكن الملف المشار إليه بواسطة fd ليس ملفًا عاديًا.

EIO حدث خطأ إدخال/إخراج أثناء القراءة من أو الكتابة إلى نظام ملفات.

ENODEV
    fd لا يشير إلى ملف عادي أو دليل. (إذا كان fd أنبوبًا أو FIFO، ينتج خطأ مختلف.)

ENOSPC
    لا توجد مساحة كافية على الجهاز الذي يحتوي على الملف المشار إليه بواسطة fd.

ENOSYS
    هذا النواة لا تنفذ fallocate().

EOPNOTSUPP
    نظام الملفات الذي يحتوي على الملف المشار إليه بواسطة fd لا يدعم هذه العملية؛ أو أن mode غير مدعوم من قبل نظام الملفات الذي يحتوي على الملف المشار إليه بواسطة fd.

EPERM
    الملف المشار إليه بواسطة fd مُعلّم على أنه غير قابل للتغيير (انظر chattr(1)).

EPERM
    mode يحدد FALLOC_FL_PUNCH_HOLE أو FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_INSERT_RANGE والملف المشار إليه بواسطة fd مُعلّم على أنه للإلحاق فقط (انظر chattr(1)).

EPERM
    مُنعت العملية بواسطة ختم ملف؛ انظر fcntl(2).

ESPIPE
    fd يشير إلى أنبوب أو FIFO.

ETXTBSY
    mode يحدد FALLOC_FL_COLLAPSE_RANGE أو FALLOC_FL_INSERT_RANGE، ولكن الملف المشار إليه بواسطة fd قيد التنفيذ حاليًا.

المعايير
لينكس.

التاريخ

fallocate()
    لينكس 2.6.23، glibc 2.10.

FALLOC_FL_*
    glibc 2.18.

انظر أيضًا
fallocate(1)، ftruncate(2)، posix_fadvise(3)، posix_fallocate(3)

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

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

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