name_to_handle_at()¶

يُعيد استدعاء النظام name_to_handle_at() مقبض ملف ومعرف وصل (mount ID) يقابل الملف المحدد عبر معطيات dirfd و pathname. يُعاد مقبض الملف عبر المعطى handle، وهو مؤشر إلى بنية بالشكل التالي:

struct file_handle {


    unsigned int  handle_bytes;   /* حجم f_handle [مدخل، مخرج] */


    int           handle_type;    /* نوع المقبض [مخرج] */


    unsigned char f_handle[0];    /* معرف الملف (حدد حجمه


                                     المستدعِي) [مخرج] */
};

تقع على عاتق المستدعِي مسؤولية تخصيص البنية بحجم كبير كافٍ لاحتواء المقبض المُعاد في f_handle. قبل الاستدعاء، يجب تهيئة الحقل handle_bytes لاحتواء الحجم المخصص لـ f_handle. (يحدد الثابت MAX_HANDLE_SZ، المُعرّف في <fcntl.h>، أقصى حجم متوقع لمقبض ملف. ليس حدًا أعلى مضمونًا لأن أنظمة الملفات المستقبلية قد تتطلب مساحة أكبر.) عند النجاح، يُحدّث الحقل handle_bytes لاحتواء عدد البايتات المكتوبة فعليًا في f_handle.

يمكن للمستدعِي اكتشاف الحجم المطلوب لبنية file_handle عبر إجراء استدعاء تكون فيه قيمة handle->handle_bytes صفرًا؛ وفي هذه الحالة، يفشل الاستدعاء بالخطأ EOVERFLOW وتُضبط قيمة handle->handle_bytes للإشارة إلى الحجم المطلوب؛ يمكن للمستدعِي بعد ذلك استخدام هذه المعلومات لتخصيص بنية بالحجم الصحيح (انظر الأمثلة أدناه). يجب توخي الحذر هنا لأن EOVERFLOW قد يشير أيضًا إلى عدم توفر مقبض ملف لهذا الاسم المعين في نظام ملفات يدعم عادةً البحث عن مقابض الملفات. يمكن اكتشاف هذه الحالة عند إرجاع الخطأ EOVERFLOW دون زيادة handle_bytes.

بخلاف استخدام حقل handle_bytes، يجب على المستدعِي معاملة بنية file_handle كنوع بيانات غير شفاف: يمكن استخدام حقلي handle_type و f_handle في استدعاء لاحق لـ open_by_handle_at(). يمكن للمستدعِي أيضًا استخدام file_handle غير الشفاف لمقارنة هوية كائنات نظام الملفات التي تم الاستعلام عنها في أوقات مختلفة وربما في مسارات مختلفة. يمكن للنظام الفرعي fanotify(7) الإبلاغ عن الأحداث بسجل معلومات يحتوي على file_handle لتحديد كائن نظام الملفات.

المعطى flags هو قناع بتات (bit mask) يُبنى عبر إجراء عملية OR لصفر أو أكثر من القيم AT_HANDLE_FID، و AT_EMPTY_PATH، و AT_SYMLINK_FOLLOW، الموصوفة أدناه.

عندما يحتوي flags على علم AT_HANDLE_FID (منذ لينكس 6.5)، يشير المستدعِي إلى أن file_handle المُعاد مطلوب لتحديد كائن نظام الملفات، وليس لفتح الملف لاحقًا، لذا يُتوقع أن استدعاءً لاحقًا لـ open_by_handle_at() باستخدام file_handle المُعاد قد يفشل.

يحدد المعطيان pathname و dirfd معًا الملف المراد الحصول على مقبض له. هناك أربع حالات متميزة:

•

إذا كان pathname سلسلة نصية غير فارغة تحتوي على مسار مطلق، فيُعاد مقبض للملف الذي يشير إليه ذلك المسار. في هذه الحالة، يُتجاهل dirfd.

•

إذا كان pathname سلسلة نصية غير فارغة تحتوي على مسار نسبي وكان لـ dirfd القيمة الخاصة AT_FDCWD، فسيُفسر pathname نسبةً إلى دليل العمل الحالي لـ المستدعِي، ويُعاد مقبض للملف الذي يشير إليه.

•

إذا كان pathname سلسلة نصية غير فارغة تحتوي على مسار نسبي وكان dirfd واصف ملف يشير إلى دليل، فسيُفسر pathname نسبةً إلى الدليل الذي يشير إليه dirfd، ويُعاد مقبض للملف الذي يشير إليه. (راجع openat(2) لشرح سبب فائدة "واصفات ملفات الدليل".)

•

إذا كان pathname سلسلة فارغة وحددت flags القيمة AT_EMPTY_PATH، فيمكن لـ dirfd أن يكون واصف ملف مفتوح يشير إلى أي نوع من الملفات، أو AT_FDCWD (بمعنى دليل العمل الحالي)، ويُعاد مقبض للملف الذي يشير إليه.

يُعيد المعطى mount_id معرفًا لوصل نظام الملفات الذي يقابل pathname. وهذا يقابل الحقل الأول في أحد السجلات في /proc/self/mountinfo. ويؤدي فتح المسار الموجود في الحقل الخامس من ذلك السجل إلى الحصول على واصف ملف لنقطة الوصل؛ يمكن استخدام واصف الملف هذا في استدعاء لاحق لـ open_by_handle_at(). يُعاد mount_id في حال نجاح الاستدعاء وأيضًا في حال الاستدعاء الذي ينتج عنه الخطأ EOVERFLOW.

مبدئيًا، لا يتبع name_to_handle_at() الارتباط التشعبي في pathname إذا كان رابطًا رمزيًا، وبالتالي يُعيد مقبضًا للرابط نفسه. أما إذا حُددت AT_SYMLINK_FOLLOW في flags، فيُتَّبع الرابط إذا كان رابطًا رمزيًا (بحيث يُعيد الاستدعاء مقبضًا للملف الذي يشير إليه الرابط).

لا يطلق name_to_handle_at() عملية وصل عندما يكون المكون الأخير من اسم المسار نقطة وصل آلي. عندما يدعم نظام ملفات مقابض الملفات ونقاط الوصل الآلي معًا، فإن استدعاء name_to_handle_at() على نقطة وصل آلي سينتهي بالخطأ EOVERFLOW دون زيادة handle_bytes. يمكن أن يحدث هذا منذ لينكس 4.13 مع NFS عند الوصول إلى دليل موجود على نظام ملفات منفصل على الخادم. في هذه الحالة، يمكن إطلاق الوصل الآلي عبر إضافة "/" إلى نهاية اسم المسار.

open_by_handle_at()¶

يفتح استدعاء النظام open_by_handle_at() الملف المشار إليه بواسطة handle، وهو مقبض ملف أُعيد بواسطة استدعاء سابق لـ name_to_handle_at().

وسيط mount_fd هو واصف ملف لأي كائن (ملف، دليل، إلخ) في نظام الملفات الموصول والذي يجب تفسير handle بالنسبة إليه. يمكن تحديد القيمة الخاصة AT_FDCWD، وتعني دليل العمل الحالي للمستدعِي.

وسيط flags مماثل لوسيط open(2). إذا كان handle يشير إلى رابط رمزي، فيجب على المستدعِي تحديد علم O_PATH، ولا يُتبع الرابط الرمزي؛ ويُتجاهل علم O_NOFOLLOW إذا حُدد.

يجب أن يمتلك المستدعِي قدرة CAP_DAC_READ_SEARCH لاستدعاء open_by_handle_at().

الحصول على معرف نظام ملفات دائم¶

يمكن إعادة استخدام معرفات التوصيل في /proc/self/mountinfo عند فصل وتوصيل أنظمة الملفات. لذلك، لا ينبغي التعامل مع معرف التوصيل الذي تُرجعه name_to_handle_at() (في *mount_id) كمعرف دائم لنظام الملفات المُوصَّل المقابل. ومع ذلك، يمكن للتطبيق استخدام المعلومات في سجل mountinfo الذي يتوافق مع معرف التوصيل لاستخلاص معرف دائم.

على سبيل المثال، يمكن استخدام اسم الجهاز في الحقل الخامس من سجل mountinfo للبحث عن UUID الجهاز المقابل عبر الروابط الرمزية في /dev/disks/by-uuid. (طريقة أكثر راحة للحصول على UUID هي استخدام مكتبة libblkid(3).) يمكن بعد ذلك عكس تلك العملية، باستخدام UUID للبحث عن اسم الجهاز، ثم الحصول على نقطة التوصيل المقابلة، لإنتاج وسيطة mount_fd التي تستخدمها open_by_handle_at().

مصدر البرنامج: t_name_to_handle_at.c¶

#define _GNU_SOURCE
#include <err.h>
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{


    int                 mount_id, fhsize, flags, dirfd;


    char                *pathname;


    struct file_handle  *fhp;


    if (argc != 2) {


        fprintf(stderr, "Usage: %s pathname\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    pathname = argv[1];


    /* Allocate file_handle structure. */


    fhsize = sizeof(*fhp);


    fhp = malloc(fhsize);


    if (fhp == NULL)


        err(EXIT_FAILURE, "malloc");


    /* Make an initial call to name_to_handle_at() to discover


       the size required for file handle. */


    dirfd = AT_FDCWD;           /* For name_to_handle_at() calls */


    flags = 0;                  /* For name_to_handle_at() calls */


    fhp->handle_bytes = 0;


    if (name_to_handle_at(dirfd, pathname, fhp,


                          &mount_id, flags) != -1


        || errno != EOVERFLOW)


    {


        fprintf(stderr, "Unexpected result from name_to_handle_at()\n");


        exit(EXIT_FAILURE);


    }


    /* Reallocate file_handle structure with correct size. */


    fhsize = sizeof(*fhp) + fhp->handle_bytes;


    fhp = realloc(fhp, fhsize);         /* Copies fhp->handle_bytes */


    if (fhp == NULL)


        err(EXIT_FAILURE, "realloc");


    /* Get file handle from pathname supplied on command line. */


    if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)


        err(EXIT_FAILURE, "name_to_handle_at");


    /* Write mount ID, file handle size, and file handle to stdout,


       for later reuse by t_open_by_handle_at.c. */


    printf("%d\n", mount_id);


    printf("%u %d   ", fhp->handle_bytes, fhp->handle_type);


    for (size_t j = 0; j < fhp->handle_bytes; j++)


        printf(" %02x", fhp->f_handle[j]);


    printf("\n");


    exit(EXIT_SUCCESS);
}

مصدر البرنامج: t_open_by_handle_at.c¶

#define _GNU_SOURCE
#include <err.h>
#include <fcntl.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <unistd.h>
/* Scan /proc/self/mountinfo to find the line whose mount ID matches


   'mount_id'. (An easier way to do this is to install and use the


   'libmount' library provided by the 'util-linux' project.)


   Open the corresponding mount path and return the resulting file


   descriptor. */
static int
open_mount_path_by_id(int mount_id)
{


    int      mi_mount_id, found;


    char     mount_path[PATH_MAX];


    char     *linep;


    FILE     *fp;


    size_t   lsize;


    ssize_t  nread;


    fp = fopen("/proc/self/mountinfo", "r");


    if (fp == NULL)


        err(EXIT_FAILURE, "fopen");


    found = 0;


    linep = NULL;


    while (!found) {


        nread = getline(&linep, &lsize, fp);


        if (nread == -1)


            break;


        nread = sscanf(linep, "%d %*d %*s %*s %s",


                       &mi_mount_id, mount_path);


        if (nread != 2) {


            fprintf(stderr, "Bad sscanf()\n");


            exit(EXIT_FAILURE);


        }


        if (mi_mount_id == mount_id)


            found = 1;


    }


    free(linep);


    fclose(fp);


    if (!found) {


        fprintf(stderr, "Could not find mount point\n");


        exit(EXIT_FAILURE);


    }


    return open(mount_path, O_RDONLY);
}
int
main(int argc, char *argv[])
{


    int                 mount_id, fd, mount_fd, handle_bytes;


    char                buf[1000];
#define LINE_SIZE 100


    char                line1[LINE_SIZE], line2[LINE_SIZE];


    char                *nextp;


    ssize_t             nread;


    struct file_handle  *fhp;


    if ((argc > 1 && strcmp(argv[1], "--help") == 0) || argc > 2) {


        fprintf(stderr, "Usage: %s [mount-path]\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    /* Standard input contains mount ID and file handle information:


         Line 1: <mount_id>


         Line 2: <handle_bytes> <handle_type>   <bytes of handle in hex>


    */


    if (fgets(line1, sizeof(line1), stdin) == NULL ||


        fgets(line2, sizeof(line2), stdin) == NULL)


    {


        fprintf(stderr, "Missing mount_id / file handle\n");


        exit(EXIT_FAILURE);


    }


    mount_id = atoi(line1);


    handle_bytes = strtoul(line2, &nextp, 0);


    /* Given handle_bytes, we can now allocate file_handle structure. */


    fhp = malloc(sizeof(*fhp) + handle_bytes);


    if (fhp == NULL)


        err(EXIT_FAILURE, "malloc");


    fhp->handle_bytes = handle_bytes;


    fhp->handle_type = strtoul(nextp, &nextp, 0);


    for (size_t j = 0; j < fhp->handle_bytes; j++)


        fhp->f_handle[j] = strtoul(nextp, &nextp, 16);


    /* Obtain file descriptor for mount point, either by opening


       the pathname specified on the command line, or by scanning


       /proc/self/mounts to find a mount that matches the 'mount_id'


       that we received from stdin. */


    if (argc > 1)


        mount_fd = open(argv[1], O_RDONLY);


    else


        mount_fd = open_mount_path_by_id(mount_id);


    if (mount_fd == -1)


        err(EXIT_FAILURE, "opening mount fd");


    /* Open file using handle and mount point. */


    fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);


    if (fd == -1)


        err(EXIT_FAILURE, "open_by_handle_at");


    /* Try reading a few bytes from the file. */


    nread = read(fd, buf, sizeof(buf));


    if (nread == -1)


        err(EXIT_FAILURE, "read");


    printf("Read %zd bytes\n", nread);


    exit(EXIT_SUCCESS);
}