lseek(2)

الاسم
lseek - إعادة وضع إزاحة ملف القراءة/الكتابة

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

موجز
#include <unistd.h>

off_t lseek(int fd, off_t offset, int whence);

الوصف
lseek() تعيد وضع إزاحة الملف لوصف الملف المفتوح المرتبط بوصف الملف fd إلى الوسيطة offset وفقًا للتوجيه whence كما يلي:

SEEK_SET
    تُضبط إزاحة الملف إلى offset بايت.

SEEK_CUR
    تُضبط إزاحة الملف إلى موقعها الحالي زائد offset بايت.

SEEK_END
    تُضبط إزاحة الملف إلى حجم الملف زائد offset بايت.

lseek() تسمح بضبط إزاحة الملف إلى ما بعد نهاية الملف (لكن هذا لا يغير حجم الملف). إذا كُتبت بيانات لاحقًا عند هذه النقطة، فإن القراءات اللاحقة للبيانات في الفجوة ("ثقب") تُرجع بايتات فارغة ('\0') حتى تُكتب البيانات فعليًا في الفجوة.

  البحث عن بيانات الملف والثقوب
منذ لينكس 3.1، يدعم لينكس القيم الإضافية التالية لـ whence:

SEEK_DATA
    اضبط إزاحة الملف إلى الموقع التالي في الملف الأكبر من أو المساوي لـ offset الذي يحتوي على بيانات. إذا أشار offset إلى بيانات، فتُضبط إزاحة الملف إلى offset.

SEEK_HOLE
    اضبط إزاحة الملف إلى الثقب التالي في الملف الأكبر من أو المساوي لـ offset. إذا أشار offset إلى منتصف ثقب، فتُضبط إزاحة الملف إلى offset. إذا لم يكن هناك ثقب بعد offset، فتُضبط إزاحة الملف إلى نهاية الملف (أي يوجد ثقب ضمني في نهاية أي ملف).

في كلتا الحالتين أعلاه، تفشل lseek() إذا أشار offset إلى ما بعد نهاية الملف.

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

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

يجب تعريف ماكرو اختبار الميزة _GNU_SOURCE للحصول على تعريفات SEEK_DATA و SEEK_HOLE من <unistd.h>.

تُدعم عمليات SEEK_HOLE و SEEK_DATA لأنظمة الملفات التالية:

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

•   OCFS (منذ لينكس 3.2)

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

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

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

•   NFS (منذ لينكس 3.18)

•   FUSE (منذ لينكس 4.5)

•   GFS2 (منذ لينكس 4.15)

قيمة الإرجاع
عند الإكمال بنجاح، تُرجع lseek() موقع الإزاحة الناتج مقاسًا بالبايتات من بداية الملف. عند الخطأ، تُرجع القيمة (off_t) -1 ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

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

EINVAL
    whence غير صالح. أو: ستكون إزاحة الملف الناتجة سالبة، أو تتجاوز نهاية جهاز قابل للبحث.

ENXIO
    whence هو SEEK_DATA أو SEEK_HOLE، و offset يتجاوز نهاية الملف، أو whence هو SEEK_DATA و offset داخل ثقب في نهاية الملف.

EOVERFLOW
    لا يمكن تمثيل إزاحة الملف الناتجة في off_t.

ESPIPE
    fd مرتبط بأنبوب أو مقبس أو FIFO.

الإصدارات
في لينكس، استخدام lseek() على جهاز طرفية يفشل مع الخطأ ESPIPE.

المعايير
POSIX.1-2024.

التاريخ
4.3BSD، SVr4، POSIX.1-1988.

SEEK_DATA
SEEK_HOLE
    Solaris 10, FreeBSD 7.0, DragonFly BSD 2.3.1, POSIX.1-2024.

ملاحظات
انظر open(2) لمناقشة العلاقة بين واصفات الملفات، أوصاف الملفات المفتوحة، والملفات.

إذا تم تعيين علم حالة الملف O_APPEND على وصف الملف المفتوح، فإن write(2) دائمًا ينقل إزاحة الملف إلى نهاية الملف، بغض النظر عن استخدام lseek().

بعض الأجهزة غير قادرة على البحث وPOSIX لا يحدد الأجهزة التي يجب أن تدعم lseek().

انظر أيضًا
dup(2), fallocate(2), fork(2), open(2), fseek(3), lseek64(3), posix_fallocate(3)

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

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

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