name_to_handle_at()¶

The name_to_handle_at() system call returns a file handle and a mount ID corresponding to the file specified by the dirfd and pathname arguments. The file handle is returned via the argument handle, which is a pointer to a structure of the following form:

struct file_handle {


    unsigned int  handle_bytes;   /* Size of f_handle [in, out] */


    int           handle_type;    /* Handle type [out] */


    unsigned char f_handle[0];    /* File identifier (sized by


                                     caller) [out] */
};

It is the caller's responsibility to allocate the structure with a size large enough to hold the handle returned in f_handle. Before the call, the handle_bytes field should be initialized to contain the allocated size for f_handle. (The constant MAX_HANDLE_SZ, defined in <fcntl.h>, specifies the maximum expected size for a file handle. It is not a guaranteed upper limit as future filesystems may require more space.) Upon successful return, the handle_bytes field is updated to contain the number of bytes actually written to f_handle.

The caller can discover the required size for the file_handle structure by making a call in which handle->handle_bytes is zero; in this case, the call fails with the error EOVERFLOW and handle->handle_bytes is set to indicate the required size; the caller can then use this information to allocate a structure of the correct size (see EXAMPLES below). Some care is needed here as EOVERFLOW can also indicate that no file handle is available for this particular name in a filesystem which does normally support file-handle lookup. This case can be detected when the EOVERFLOW error is returned without handle_bytes being increased.

Other than the use of the handle_bytes field, the caller should treat the file_handle structure as an opaque data type: the handle_type and f_handle fields can be used in a subsequent call to open_by_handle_at(). The caller can also use the opaque file_handle to compare the identity of filesystem objects that were queried at different times and possibly at different paths. The fanotify(7) subsystem can report events with an information record containing a file_handle to identify the filesystem object.

The flags argument is a bit mask constructed by ORing together zero or more of AT_HANDLE_FID, AT_EMPTY_PATH, and AT_SYMLINK_FOLLOW, described below.

When flags contain the AT_HANDLE_FID (since Linux 6.5) flag, the caller indicates that the returned file_handle is needed to identify the filesystem object, and not for opening the file later, so it should be expected that a subsequent call to open_by_handle_at() with the returned file_handle may fail.

Together, the pathname and dirfd arguments identify the file for which a handle is to be obtained. There are four distinct cases:

•

If pathname is a nonempty string containing an absolute pathname, then a handle is returned for the file referred to by that pathname. In this case, dirfd is ignored.

•

If pathname is a nonempty string containing a relative pathname and dirfd has the special value AT_FDCWD, then pathname is interpreted relative to the current working directory of the caller, and a handle is returned for the file to which it refers.

•

If pathname is a nonempty string containing a relative pathname and dirfd is a file descriptor referring to a directory, then pathname is interpreted relative to the directory referred to by dirfd, and a handle is returned for the file to which it refers. (See openat(2) for an explanation of why "directory file descriptors" are useful.)

•

If pathname is an empty string and flags specifies the value AT_EMPTY_PATH, then dirfd can be an open file descriptor referring to any type of file, or AT_FDCWD, meaning the current working directory, and a handle is returned for the file to which it refers.

The mount_id argument returns an identifier for the filesystem mount that corresponds to pathname. This corresponds to the first field in one of the records in /proc/self/mountinfo. Opening the pathname in the fifth field of that record yields a file descriptor for the mount point; that file descriptor can be used in a subsequent call to open_by_handle_at(). mount_id is returned both for a successful call and for a call that results in the error EOVERFLOW.

By default, name_to_handle_at() does not dereference pathname if it is a symbolic link, and thus returns a handle for the link itself. If AT_SYMLINK_FOLLOW is specified in flags, pathname is dereferenced if it is a symbolic link (so that the call returns a handle for the file referred to by the link).

name_to_handle_at() does not trigger a mount when the final component of the pathname is an automount point. When a filesystem supports both file handles and automount points, a name_to_handle_at() call on an automount point will return with error EOVERFLOW without having increased handle_bytes. This can happen since Linux 4.13 with NFS when accessing a directory which is on a separate filesystem on the server. In this case, the automount can be triggered by adding a "/" to the end of the pathname.

open_by_handle_at()¶

The open_by_handle_at() system call opens the file referred to by handle, a file handle returned by a previous call to name_to_handle_at().

The mount_fd argument is a file descriptor for any object (file, directory, etc.) in the mounted filesystem with respect to which handle should be interpreted. The special value AT_FDCWD can be specified, meaning the current working directory of the caller.

The flags argument is as for open(2). If handle refers to a symbolic link, the caller must specify the O_PATH flag, and the symbolic link is not dereferenced; the O_NOFOLLOW flag, if specified, is ignored.

The caller must have the CAP_DAC_READ_SEARCH capability to invoke open_by_handle_at().

Obtaining a persistent filesystem ID¶

The mount IDs in /proc/self/mountinfo can be reused as filesystems are unmounted and mounted. Therefore, the mount ID returned by name_to_handle_at() (in *mount_id) should not be treated as a persistent identifier for the corresponding mounted filesystem. However, an application can use the information in the mountinfo record that corresponds to the mount ID to derive a persistent identifier.

For example, one can use the device name in the fifth field of the mountinfo record to search for the corresponding device UUID via the symbolic links in /dev/disks/by-uuid. (A more comfortable way of obtaining the UUID is to use the libblkid(3) library.) That process can then be reversed, using the UUID to look up the device name, and then obtaining the corresponding mount point, in order to produce the mount_fd argument used by open_by_handle_at().

Program source: 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);
}

Program source: 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);
}