sync_file_range(2)

الاسم
sync_file_range - مزامنة مقطع ملف مع القرص

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

موجز
#define _GNU_SOURCE         /* انظر feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>

int sync_file_range(int fd, off_t offset, off_t nbytes,
                    unsigned int flags);

الوصف
تسمح sync_file_range() بالتحكم الدقيق عند مزامنة الملف المفتوح المشار إليه بواصف الملف fd مع القرص.

offset هو البايت الابتدائي لنطاق الملف المراد مزامنته. يحدد nbytes طول النطاق المراد مزامنته، بالبايتات؛ إذا كان nbytes صفرًا، فستتم مزامنة جميع البايتات من offset حتى نهاية الملف. تتم المزامنة بوحدات حجم صفحة النظام: يتم تقريب offset لأسفل إلى حد صفحة؛ يتم تقريب (offset+nbytes-1) لأعلى إلى حد صفحة.

يمكن أن تتضمن وسيطة قناع البتات flags أيًا من القيم التالية:

SYNC_FILE_RANGE_WAIT_BEFORE
    انتظر كتابة جميع الصفحات في النطاق المحدد التي تم إرسالها بالفعل إلى برنامج تشغيل الجهاز للكتابة قبل تنفيذ أي كتابة.

SYNC_FILE_RANGE_WRITE
    ابدأ كتابة جميع الصفحات المتسخة في النطاق المحدد التي لم يتم إرسالها حاليًا للكتابة. لاحظ أن هذا قد يحظر حتى إذا حاولت كتابة أكثر من حجم قائمة انتظار الطلبات.

SYNC_FILE_RANGE_WAIT_AFTER
    انتظر كتابة جميع الصفحات في النطاق بعد تنفيذ أي كتابة.

يُسمح بتحديد flags كـ 0، كعملية عدم فعل.

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

  بعض التفاصيل
ستكتشف SYNC_FILE_RANGE_WAIT_BEFORE و SYNC_FILE_RANGE_WAIT_AFTER أي أخطاء إدخال/إخراج أو حالات ENOSPC وستعيد هذه إلى المستدعي.

التركيبات المفيدة لبتات flags هي:

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
    تضمن أن جميع الصفحات في النطاق المحدد التي كانت متسخة عند استدعاء sync_file_range() يتم وضعها تحت الكتابة. هذه عملية بدء كتابة لتكامل البيانات.

SYNC_FILE_RANGE_WRITE
    ابدأ كتابة جميع الصفحات المتسخة في النطاق المحدد التي ليست حاليًا تحت الكتابة. هذه عملية مسح غير متزامن إلى القرص. هذه ليست مناسبة لعمليات تكامل البيانات.

SYNC_FILE_RANGE_WAIT_BEFORE (أو SYNC_FILE_RANGE_WAIT_AFTER)
    انتظر اكتمال كتابة جميع الصفحات في النطاق المحدد. يمكن استخدام هذا بعد عملية سابقة SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE لانتظار اكتمال تلك العملية، والحصول على نتيجتها.

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER
    هذه عملية كتابة لتكامل البيانات تضمن أن جميع الصفحات في النطاق المحدد التي كانت متسخة عند استدعاء sync_file_range() يتم إيداعها على القرص.

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

الأخطاء

EBADF
    fd ليس واصف ملف صالح.

EINVAL
    يحدد flags بتة غير صالحة؛ أو أن offset أو nbytes غير صالح.

EIO خطأ إدخال/إخراج.

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

ENOSPC
    نفاد مساحة القرص.

ESPIPE
    يشير fd إلى شيء آخر غير ملف عادي أو جهاز كتلة أو دليل.

الإصدارات

  sync_file_range2()
بعض البنى (مثل PowerPC، ARM) تحتاج وسائط 64-bit لتكون محاذية في زوج مناسب من المسجلات. على هذه البنى، توقيع استدعاء sync_file_range() الموضح في الملخص سيجبر مسجلاً على أن يُهدر كحشوة بين وسيطي fd وoffset. (انظر syscall(2) للتفاصيل.) لذلك، تعرف هذه البنى استدعاء نظام مختلفاً يرتب الوسائط بشكل مناسب:

    int sync_file_range2(int fd, unsigned int flags,
                         off_t offset, off_t nbytes);

سلوك استدعاء النظام هذا مطابق تماماً لـ sync_file_range() فيما عدا ذلك.

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

التاريخ
لينكس 2.6.17.

  sync_file_range2()
استدعاء نظام بهذا التوقيع ظهر أولاً على بنية ARM في لينكس 2.6.20، بالاسم arm_sync_file_range(). أُعيدت تسميته في لينكس 2.6.22، عندما أُضيف استدعاء النظام المماثل لـ PowerPC. على البنى حيث دعم glibc متوفر، يغلف glibc بشفافية sync_file_range2() تحت الاسم sync_file_range().

ملاحظات
_FILE_OFFSET_BITS يجب أن يُعرف كـ 64 في الكود الذي يأخذ عنوان sync_file_range، إذا كان الكود مقصوداً ليكون محمولاً إلى منصات x86 وARM 32-bit التقليدية حيث عرض off_t مبدئي هو 32 بت.

انظر أيضًا
fdatasync(2)، fsync(2)، msync(2)، sync(2)

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

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

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