الاسم

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

#include <fcntl.h>            /* تعريف ثوابت AT_* */
#include <sys/stat.h>

int utimensat(int dirfd, const char *path,
              const struct timespec times[_Nullable 2], int flags);
int futimens(int fd, const struct timespec times[_Nullable 2]);

utimensat():

    منذ glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    قبل glibc 2.10:
        _ATFILE_SOURCE

futimens():

    منذ glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    قبل glibc 2.10:
        _GNU_SOURCE

تحدّث utimensat() وfutimens() أختام الوقت للملف بدقة نانوثانية. يتناقض هذا مع utime(2) وutimes(2) التاريخيتين، اللتين تسمحان فقط بدقة ثانية وميكروثانية على التوالي عند ضبط أختام الوقت للملف.

مع utimensat() يُحدد الملف عبر اسم المسار المعطى في path. مع futimens() يُحدد الملف الذي ستُحدّث أختام وقته عبر واصف ملف مفتوح، fd.

لكلا الاستدعاءين، تُحدد أختام الوقت الجديدة للملف في المصفوفة times: يُحدد times[0] "وقت الوصول الأخير" الجديد (atime)؛ يُحدد times[1] "وقت التعديل الأخير" الجديد (mtime). يُحدد كل عنصر من عناصر times وقتًا بعدد الثواني والنانوثوان منذ العصر، 1970-01-01 00:00:00 +0000 (UTC). تُنقل هذه المعلومات في بنية timespec(3).

تُضبط أختام الوقت المحدّثة للملف إلى أكبر قيمة يدعمها نظام الملفات لا تتجاوز الوقت المحدد.

إذا كان حقل tv_nsec لإحدى بنى timespec يحمل القيمة الخاصة UTIME_NOW، فإن ختم الوقت المقابل للملف يُضبط إلى الوقت الحالي. إذا كان حقل tv_nsec لإحدى بنى timespec يحمل القيمة الخاصة UTIME_OMIT، فإن ختم الوقت المقابل للملف يُترك دون تغيير. في كلتا هاتين الحالتين، يُتجاهل قيمة حقل tv_sec المقابل.

إذا كان times NULL، فإن كلا الختمين يُضبطان إلى الوقت الحالي.

سيُضبط وقت تغيير الحالة (ctime) إلى الوقت الحالي، حتى لو لم تتغير أختام الوقت الأخرى فعليًا.

عند النجاح، تُرجع utimensat() وfutimens() 0. عند الخطأ، يُرجع -1 ويُضبط errno للإشارة إلى الخطأ.

EACCES

times هو NULL، أو كلا قيمتي tv_nsec هما UTIME_NOW، ولا يتطابق معرف المستخدم الفعّال للمستدعي مع مالك الملف، وليس لدى المستدعي صلاحية الكتابة إلى الملف، والمستدعي ليس مميزًا (لينكس: ليس لديه إما القدرة CAP_FOWNER أو CAP_DAC_OVERRIDE).

EBADF

(futimens()) fd ليس واصف ملف صالحًا.

EBADF

(utimensat()) path نسبي ولكن dirfd ليس AT_FDCWD ولا واصف ملف صالحًا.

EFAULT

أشار times إلى عنوان غير صالح؛ أو، كان dirfd AT_FDCWD، و path هو NULL أو عنوان غير صالح.

EINVAL

قيمة غير صالحة في flags.

EINVAL

قيمة غير صالحة في أحد حقلي tv_nsec (قيمة خارج النطاق [0, 999,999,999]، وليست UTIME_NOW أو UTIME_OMIT)؛ أو قيمة غير صالحة في أحد حقلي tv_sec.

EINVAL

path هو NULL، و dirfd ليس AT_FDCWD، و flags يحتوي على AT_SYMLINK_NOFOLLOW.

ELOOP

(utimensat()) تمت مصادفة عدد كبير جدًا من الروابط الرمزية أثناء حل path.

ENAMETOOLONG

(utimensat()) path طويل جدًا.

ENOENT

(utimensat()) أحد مكونات path لا يشير إلى دليل أو ملف موجود، أو path هو سلسلة فارغة.

ENOTDIR

(utimensat()) path نسبي، لكن dirfd ليس AT_FDCWD ولا واصف ملف يشير إلى دليل؛ أو، أحد مكونات البادئة لـ path ليس دليلاً.

EPERM

حاول المتصل تغيير طابع زمني واحد أو كليهما إلى قيمة غير الوقت الحالي، أو تغيير أحد الطوابع الزمنية إلى الوقت الحالي مع ترك الطابع الزمني الآخر دون تغيير، (أي times ليس NULL، ولا حقل tv_nsec هو UTIME_NOW، ولا حقل tv_nsec هو UTIME_OMIT) وأيضًا:

EROFS

الملف موجود في نظام ملفات للقراءة فقط.

ESRCH

(utimensat()) تم رفض إذن البحث لأحد مكونات البادئة لـ path.

للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).

POSIX.1-2024.

utimensat()

لينكس 2.6.22، glibc 2.6. POSIX.1-2008.

futimens()

glibc 2.6. POSIX.1-2008.

utimensat() يلغي futimesat(2).

في لينكس، لا يمكن تغيير الطوابع الزمنية لملف مُعلّم كغير قابل للتغيير، والتغيير الوحيد المسموح به للملفات المُعلّمة كملحق فقط هو تعيين الطوابع الزمنية إلى الوقت الحالي. (هذا متسق مع السلوك التاريخي لـ utime(2) و utimes(2) على لينكس.)

إذا تم تحديد كلا حقلي tv_nsec كـ UTIME_OMIT، فإن تنفيذ لينكس لـ utimensat() ينجح حتى لو كان الملف المشار إليه بواسطة dirfd و path غير موجود.

تعاني utimensat() و futimens() من عدة أخطاء قبل لينكس 2.6.26. هذه الأخطاء إما عدم امتثال لمواصفات مسودة POSIX.1 أو عدم تناسق مع سلوك لينكس التاريخي.

• يحدد POSIX.1 أنه إذا كان أحد حقول tv_nsec له القيمة UTIME_NOW أو UTIME_OMIT، فيجب تجاهل قيمة حقل tv_sec المقابل. بدلاً من ذلك، يُطلب أن تكون قيمة حقل tv_sec 0 (أو ينتج الخطأ EINVAL).
• تعني الأخطاء المختلفة أنه لأغراض التحقق من الإذن، لا يتم دائمًا معالجة الحالة التي يتم فيها تعيين كلا حقلي tv_nsec إلى UTIME_NOW بنفس طريقة تحديد times كـ NULL، والحالة التي تكون فيها قيمة tv_nsec واحدة UTIME_NOW والأخرى UTIME_OMIT لا يتم معالجتها بنفس طريقة تحديد times كمؤشر إلى مصفوفة من الهياكل التي تحتوي على قيم زمنية عشوائية. نتيجة لذلك، في بعض الحالات: أ) يمكن تحديث الطوابع الزمنية للملف بواسطة عملية لا ينبغي أن يكون لها إذن لإجراء التحديثات؛ ب) لا يمكن تحديث الطوابع الزمنية للملف بواسطة عملية يجب أن يكون لها إذن لإجراء التحديثات؛ و ج) يتم إرجاع قيمة errno خاطئة في حالة حدوث خطأ.
• يقول POSIX.1 أن العملية التي لديها إذن كتابة إلى الملف يمكنها إجراء استدعاء مع times كـ NULL، أو مع times يشير إلى مصفوفة من الهياكل التي يكون فيها كلا حقلي tv_nsec UTIME_NOW، من أجل تحديث كلا الطابعين الزمنيين إلى الوقت الحالي. ومع ذلك، futimens() بدلاً من ذلك يتحقق مما إذا كان وضع الوصول لواصف الملف يسمح بالكتابة.

chattr(1), touch(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), timespec(3), inode(7), path_resolution(7), symlink(7)

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

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

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