truncate(2)

الاسم
truncate, ftruncate - اقتطاع ملف إلى طول محدد

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

موجز
#include <unistd.h>

int truncate(const char *path, off_t length);
int ftruncate(int fd, off_t length);

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

truncate():
    _XOPEN_SOURCE >= 500
        || /* منذ glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
        || /* glibc <= 2.19: */ _BSD_SOURCE

ftruncate():
    _XOPEN_SOURCE >= 500
        || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L
        || /* glibc <= 2.19: */ _BSD_SOURCE

الوصف
تتسبب الدالتان truncate() و ftruncate() في اقتطاع الملف العادي المسمى بـ path أو المشار إليه بـ fd إلى حجم يساوي بالضبط length بايت.

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

لا يتغير إزاحة الملف.

إذا تغير الحجم، فتُحدث حقلا st_ctime و st_mtime (على التوالي، وقت آخر تغيير للحالة ووقت آخر تعديل؛ انظر inode(7)) للملف، وقد تُمسح بتات وضع set-user-ID و set-group-ID.

مع ftruncate()، يجب أن يكون الملف مفتوحًا للكتابة؛ مع truncate()، يجب أن يكون الملف قابلًا للكتابة.

قيمة الإرجاع
عند النجاح، يُعاد الصفر. وعند حدوث خطأ، يُعاد الرقم -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء
بالنسبة لـ truncate():

EACCES
    يُرفض إذن البحث لمكون من بادئة المسار، أو أن الملف المسمى غير قابل للكتابة من قبل المستخدم. (انظر أيضًا path_resolution(7).)

EFAULT
    يشير الوسيط path إلى خارج مساحة العنوان المخصصة للعملية.

EFBIG
    الوسيط length أكبر من الحد الأقصى لحجم الملف. (XSI)

ENOSPC
    لا توجد مساحة كافية متبقية على الجهاز لتمديد حجم الملف إلى length المعطى.

EINTR
    أثناء الحظر انتظارًا للإكمال، قُطعت الاستدعاء بواسطة معالج إشارة؛ انظر fcntl(2) و signal(7).

EINVAL
    الوسيط length سالب أو أكبر من الحد الأقصى لحجم الملف.

EIO حدث خطأ إدخال/إخراج أثناء تحديث inode.

EISDIR
    الملف المسمى هو دليل.

ELOOP
    صودفت روابط رمزية كثيرة جدًا عند ترجمة اسم المسار.

ENAMETOOLONG
    تجاوز مكون من اسم المسار 255 حرفًا، أو تجاوز اسم المسار بالكامل 1023 حرفًا.

ENOENT
    الملف المسمى غير موجود.

ENOTDIR
    أحد مكونات بادئة المسار ليس دليلاً.

EPERM
    نظام الملفات الأساسي لا يدعم تمديد ملف يتجاوز حجمه الحالي.

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

EROFS
    الملف المسمى يقع في نظام ملفات للقراءة فقط.

ETXTBSY
    الملف هو ملف قابل للتنفيذ يُنفذ حاليًا.

بالنسبة لـ ftruncate()، تنطبق نفس الأخطاء، ولكن بدلاً من الأشياء التي قد تكون خاطئة مع path، لدينا الآن أشياء قد تكون خاطئة مع واصف الملف fd:

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

EBADF أو EINVAL
    fd غير مفتوح للكتابة.

EINVAL
    fd لا يشير إلى ملف عادي أو كائن ذاكرة مشتركة POSIX.

EINVAL أو EBADF
    واصف الملف fd غير مفتوح للكتابة. يسمح POSIX، ويجب على التطبيقات المحمولة التعامل مع أي من الخطأين لهذه الحالة. (ينتج Linux EINVAL.)

الإصدارات
التفاصيل في DESCRIPTION مخصصة للأنظمة المتوافقة مع XSI. بالنسبة للأنظمة غير المتوافقة مع XSI، يسمح معيار POSIX بسلوكين لـ ftruncate() عندما يتجاوز length طول الملف (لاحظ أن truncate() غير محدد على الإطلاق في مثل هذه البيئة): إما إرجاع خطأ، أو تمديد الملف. مثل معظم تطبيقات UNIX، يتبع Linux متطلب XSI عند التعامل مع أنظمة الملفات الأصلية. ومع ذلك، لا تسمح بعض أنظمة الملفات غير الأصلية باستخدام truncate() و ftruncate() لتمديد ملف يتجاوز طوله الحالي: مثال بارز على Linux هو VFAT.

في بعض معماريات 32 بت، تختلف بصمة الاستدعاء لنداءات النظام هذه، للأسباب الموصوفة في syscall(2).

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

التاريخ
POSIX.1-2001،‏ SVr4،‏ 4.2BSD.

لم تُصمم استدعاءات النظام الأصلية Linux truncate() و ftruncate() للتعامل مع إزاحات الملفات الكبيرة. وبالتالي، أضاف Linux 2.4 استدعاءات النظام truncate64() و ftruncate64() التي تتعامل مع الملفات الكبيرة. ومع ذلك، يمكن تجاهل هذه التفاصيل من قبل التطبيقات التي تستخدم glibc، حيث تستخدم دوال الغلاف الخاصة بها بشفافية استدعاءات النظام الأحدث عند توفرها.

ملاحظات
يمكن استخدام ftruncate() أيضًا لتعيين حجم كائن ذاكرة مشتركة POSIX؛ انظر shm_open(3).

العلل
خلل في ملف الرأس في glibc 2.12 يعني أن القيمة الدنيا لـ _POSIX_C_SOURCE المطلوبة لكشف تعريف ftruncate() كانت 200809L بدلاً من 200112L. تم إصلاح هذا في إصدارات glibc اللاحقة.

انظر أيضًا
truncate(1), open(2), stat(2), path_resolution(7)

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

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

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