Manpages - open_by_handle_at.2

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 are needed only by a subsequent call to *open_by_handle_at*().

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

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.

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*().

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*().

  #define _GNU_SOURCE
  #include <sys/types.h>
  #include <sys/stat.h>
  #include <fcntl.h>
  #include <stdio.h>
  #include <stdlib.h>
  #include <unistd.h>
  #include <errno.h>
  #include <string.h>

  #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                          } while (0)

  int
  main(int argc, char *argv[])
  {
      struct file_handle *fhp;
      int mount_id, fhsize, flags, dirfd;
      char *pathname;

      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)
          errExit("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)
          errExit("realloc");

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

      if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)
          errExit("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 (int j = 0; j < fhp->handle_bytes; j++)
          printf(" %02x", fhp->f_handle[j]);
      printf("\n");

      exit(EXIT_SUCCESS);
  }

  #define _GNU_SOURCE
  #include <sys/types.h>
  #include <sys/stat.h>
  #include <fcntl.h>
  #include <limits.h>
  #include <stdio.h>
  #include <stdlib.h>
  #include <unistd.h>
  #include <string.h>

  #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                          } while (0)

  /* 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)
  {
      char *linep;
      size_t lsize;
      char mount_path[PATH_MAX];
      int mi_mount_id, found;
      ssize_t nread;
      FILE *fp;

      fp = fopen("/proc/self/mountinfo", "r");
      if (fp == NULL)
          errExit("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[])
  {
      struct file_handle *fhp;
      int mount_id, fd, mount_fd, handle_bytes;
      ssize_t nread;
      char buf[1000];
  #define LINE_SIZE 100
      char line1[LINE_SIZE], line2[LINE_SIZE];
      char *nextp;

      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)
          errExit("malloc");

      fhp->handle_bytes = handle_bytes;

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

      for (int 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)
          errExit("opening mount fd");

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

      fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
      if (fd == -1)
          errExit("open_by_handle_at");

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

      nread = read(fd, buf, sizeof(buf));
      if (nread == -1)
          errExit("read");

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

      exit(EXIT_SUCCESS);
  }