utimensat(2)

الاسم
utimensat, futimens - تغيير أختام الوقت للملف بدقة نانوثانية

المكتبة
مكتبة سي المعيارية (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]);

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

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) إلى الوقت الحالي، حتى لو لم تتغير أختام الوقت الأخرى فعليًا.

  متطلبات الأذونات
لضبط كلا ختمي الوقت للملف إلى الوقت الحالي (أي، times هو NULL، أو كلا حقلي tv_nsec يحددان UTIME_NOW)، إما:

•   يجب أن يكون لدى المستدعي صلاحية الكتابة إلى الملف؛

•   يجب أن يتطابق معرف المستخدم الفعّال للمستدعي مع مالك الملف؛ أو

•   يجب أن يكون لدى المستدعي الامتيازات المناسبة.

لإجراء أي تغيير غير ضبط كلا الختمين إلى الوقت الحالي (أي، times ليس NULL، ولا حقل tv_nsec هو UTIME_NOW ولا حقل tv_nsec هو UTIME_OMIT)، يجب أن ينطبق الشرط 2 أو 3 أعلاه.

إذا تم تحديد كلا حقلي tv_nsec كـ UTIME_OMIT، فلا تُجرى أي فحوصات لملكية الملف أو أذوناته، ولا تُعدّل أختام الوقت للملف، ولكن قد تُكتشف شروط خطأ أخرى.

  خصوصيات utimensat()
إذا كان path نسبيًا، فإنه يُفسر مبدئيًا بالنسبة إلى الدليل المشار إليه بواسطة واصف الملف المفتوح، dirfd (بدلاً من نسبته إلى دليل العمل الحالي للعملية المستدعية، كما تفعل utimes(2) لاسم مسار نسبي). انظر openat(2) لشرح لماذا يمكن أن يكون هذا مفيدًا.

إذا كان المسار path نسبيا وكان dirfd هو القيمة الخاصة AT_FDCWD، فسيُفسر path نسبة إلى دليل العمل الحالي للعملية المستدعِيَة (مثل utimes(2)).

إذا كان المسار path مطلقاً، فُيتجاهل dirfd.

وسيطة flags هي قناع بتات يُنشأ بواسطة OR معًا صفر أو أكثر من القيم التالية المعرفة في <fcntl.h>:

AT_EMPTY_PATH (منذ لينكس 5.8)
    إذا كان path سلسلة فارغة، فسيُعمل على الملف الذي يشير إليه dirfd (والذي ربما تم الحصول عليه باستخدام الراية O_PATH في open(2)). في هذه الحالة، يمكن لـ dirfd أن يشير إلى أي نوع من الملفات، وليس فقط المجلدات. وإذا كان dirfd هو AT_FDCWD، فسيُنادى على مجلد العمل الحالي. هذه الراية خاصة بلينكس؛ عرّف _GNU_SOURCE للحصول على تعريفها.

AT_SYMLINK_NOFOLLOW
    إذا حدد path رابطًا رمزيًا، فحدّث أختام الوقت للرابط، بدلاً من الملف الذي يشير إليه.

قيمة الإرجاع
عند النجاح، تُرجع 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) وأيضًا:

    •   معرف المستخدم الفعّال للمتصل لا يتطابق مع مالك الملف، والمتصل ليس له صلاحية (لينكس: لا يملك إمكانية CAP_FOWNER)؛ أو،

    •   الملف مُعلّم كملحق فقط أو غير قابل للتغيير (انظر chattr(1)).

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

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

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
utimensat(), futimens() | سلامة الخيوط | MT-Safe

الإصدارات

  اختلافات ABI بين مكتبة C والنواة
في لينكس، futimens() هي دالة مكتبة مطبقة فوق استدعاء النظام utimensat(). لدعم هذا، يطبق استدعاء النظام utimensat() في لينكس ميزة غير قياسية: إذا كان path هو NULL، فإن الاستدعاء يعدل الطوابع الزمنية للملف المشار إليه بواسطة واصف الملف dirfd (الذي قد يشير إلى أي نوع من الملفات). باستخدام هذه الميزة، يتم تنفيذ الاستدعاء futimens(fd, times) كالتالي:

    utimensat(fd, NULL, times, 0);

لاحظ، مع ذلك، أن غلاف glibc لـ utimensat() يمنع تمرير NULL كقيمة لـ path: دالة الغلاف ترجع الخطأ EINVAL في هذه الحالة.

المعايير
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 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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