name_to_handle_at()¶

struct file_handle {
    unsigned int  handle_bytes;   /* taille de f_handle [in, out] */
    int           handle_type;    /* type du gestionnaire handle [out] */
    unsigned char f_handle[0];    /* identifiant du fichier (dont la taille est définie
                                     lors de l'appel) [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 EXAMPLE 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.

Mise à part l'utilisation du champ handle_bytes, l'appelant doit considérer la structure file_handle comme une « boîte noire » : les champs handle_type et f_handle ne sont utiles que pour un appel ultérieur à open_by_handle_at().

L'argument flags est un masque de bits construit par OU binaire entre zéro ou plus de AT_EMPTY_PATH et AT_SYMLINK_FOLLOW, comme décrit plus bas.

Ensemble, les arguments pathname et dirfd désignent le fichier pour lequel on souhaite obtenir un gestionnaire. On distingue quatre cas :

• Si pathname est une chaîne non vide contenant un chemin d'accès absolu, alors un gestionnaire est renvoyé pour le fichier indiqué par le chemin. Dans ce cas, dirfd est ignoré.
• Si pathname est une chaîne non vide contenant un chemin relatif, et si dirfd a la valeur spéciale AT_FDCWD, alors pathname est interprété par rapport au répertoire courant du processus appelant, et un gestionnaire est renvoyé pour le fichier indiqué par le chemin.
• 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.)
• Si pathname est une chaîne vide, et si flags précise la valeur de AT_EMPTY_PATH, alors dirfd peut être un descripteur de fichiers ouvert faisant référence à n'importe quel type de fichier ou à AT_FDCWD (répertoire de travail courant), et un gestionnaire est renvoyé pour le fichier auquel il fait référence.

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.

Par défaut, name_to_handle_at() ne déréférence pas pathname s'il s'agit d'un lien symbolique, et donc ne renvoie pas d'indicateur pour le lien symbolique. Si AT_SYMLINK_FOLLOW est précisé dans flags, pathname est déréférencé s'il s'agit d'un lien symbolique (de sorte que l'appel renvoie un indicateur pour le fichier vers lequel pointe le lien symbolique).

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()¶

L'argument mount_fd est un descripteur de fichier pour n'importe quel type d'objet (fichier, répertoire, etc.) du système de fichiers monté qui permet d'interpréter l'indicateur de fichier (handle). La valeur spéciale AT_FDCWD peut être précisée, et indique le répertoire courant du processus appelant.

L'argument flags a la même fonction que pour open(2). Si l'indicateur handle fait référence à un lien symbolique, le processus appelant doit préciser l'attribut O_PATH et le lien symbolique n'est pas déréférencé. L'attribut O_NOFOLLOW est ignoré.

L'appelant doit avoir la capacité CAP_DAC_READ_SEARCH pour utiliser open_by_handle_at().

Obtenir un identifiant persistant de système de fichier¶

Par exemple, on peut utiliser le nom de périphérique présent dans le cinquième champ de mountinfo pour retrouver l'UUID du périphérique correspondant au moyen des liens symboliques de /dev/disks/by-uuid. (Un moyen plus simple d'obtenir cet UUID consiste à utiliser la bibliothèque libblkid(3)). Cette façon de procéder peut être inversée, en utilisant l'UUID pour retrouver le nom du périphérique, et ainsi obtenir le point de montage correspondant, et enfin construire l'argument de mount_fd utile à open_by_handle_at().

Source du programme : t_name_to_handle_at.c¶

#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, j;
    char *pathname;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s pathname\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    pathname = argv[1];
    /* Alloue la structure file_handle */
    fhsize = sizeof(*fhp);
    fhp = malloc(fhsize);
    if (fhp == NULL)
        errExit("malloc");
    /* Effectue un appel initial à name_to_handle_at() afin de connaître
       la taille nécessaire à l'indicateur de fichier */
    dirfd = AT_FDCWD;           /* pour les appels à name_to_handle_at() */
    flags = 0;                  /* Pour les appels à  name_to_handle_at() */
    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);
    }
    /* Ré-alloue la structure file_handle avec la bonne taille */
    fhsize = sizeof(struct file_handle) + fhp->handle_bytes;
    fhp = realloc(fhp, fhsize);         /* Copie fhp->handle_bytes */
    if (fhp == NULL)
        errExit("realloc");
    /* Retrouve l'indicateur de fichier à partir
       du chemin fourni dans la ligne de commande */
    if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)
        errExit("name_to_handle_at");
    /* Écrit l'identifiant de montage, la taille de l'indicateur et
       l'indicateur vers la sortie standard
       pour être utilisé plus tard par t_open_by_handle_at.c */
    printf("%d\n", mount_id);
    printf("%d %d   ", fhp->handle_bytes, fhp->handle_type);
    for (j = 0; j < fhp->handle_bytes; j++)
        printf(" %02x", fhp->f_handle[j]);
    printf("\n");
    exit(EXIT_SUCCESS);
}

Source du programme : t_open_by_handle_at.c¶

#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)
/* Parcourt /proc/self/mountinfo pour trouver la ligne correspondant à
   l'ID de montage 'mount_id'. (Une méthode plus simple consiste à
   installer et à utiliser la bibliothèque (aqlibmount' fournie par le
   projet 'util-linux'.)
   Ouvre le point de montage correspondant et renvoie le descripteur de fichier associé. */
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, "Point de montage non trouvé\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, j;
    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);
    }
    /* L'entrée standard contient l'identifiant de montage et les informations du l'indicateur :
         Ligne 1: <mount_id>
         Ligne 2: <handle_bytes> <handle_type>   <octets du descripteur en hexadécimal>
    */
    if ((fgets(line1, sizeof(line1), stdin) == NULL) ||
           (fgets(line2, sizeof(line2), stdin) == NULL)) {
        fprintf(stderr, "mount_id ou descripteur de fichier absent\n");
        exit(EXIT_FAILURE);
    }
    mount_id = atoi(line1);
    handle_bytes = strtoul(line2, &nextp, 0);
    /* handle_bytes étant connu, on peut maintenant allouer la structure file_handle */
    fhp = malloc(sizeof(struct file_handle) + handle_bytes);
    if (fhp == NULL)
        errExit("malloc");
    fhp->handle_bytes = handle_bytes;
    fhp->handle_type = strtoul(nextp, &nextp, 0);
    for (j = 0; j < fhp->handle_bytes; j++)
        fhp->f_handle[j] = strtoul(nextp, &nextp, 16);
    /* Récupère le descripteur de fichier du point de montage, soit en ouvrant
       le chemin indiqué dans la ligne de commande, soit en parcourant
       /proc/self/mounts pour retrouver un montage qui corresponde à 'mount_id'
       qui a été reçu de 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");
    /* Ouvre le fichier en utilisant l'indicateur et le point de montage */
    fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
    if (fd == -1)
        errExit("open_by_handle_at");
    /* On essaie de lire quelques octets depuis le fichier */
    nread = read(fd, buf, sizeof(buf));
    if (nread == -1)
        errExit("read");
    printf("Read %zd bytes\n", nread);
    exit(EXIT_SUCCESS);
}