name_to_handle_at()

L'appel système name_to_handle_at() renvoie un gestionnaire de fichier et un identifiant de montage (« mount ID ») correspondant au fichier désigné par les arguments dirfd et pathname. Le gestionnaire de fichier est renvoyé au moyen de l'argument handle. Cet argument est un pointeur vers une structure qui présente la forme suivante :

struct file_handle {
    unsigned int  handle_bytes;   /* taille de f_handle [in, out] */
    int           handle_type;    /* type du gestionnaire [out] */
    unsigned char f_handle[0];    /* identifiant du fichier (taille
                                     définie par l’appelant) [out] */
};

L'appelant à l'origine de l'appel doit s'assurer que la structure est créée avec une taille suffisante pour contenir le gestionnaire renvoyé dans f_handle. Avant l'appel, le champ handle_bytes devrait être initialisé de sorte que l'espace alloué puisse recevoir f_handle. (La constante MAX_HANDLE_SZ, définie dans <fcntl.h>, précise la taille maximale autorisée pour un gestionnaire de fichier. La limite supérieure n'est pas garantie car de futurs systèmes de fichiers pourraient avoir besoin de davantage d'espace). Lorsque l'appel réussit, le champ handle_bytes est mis à jour afin de contenir le nombre d'octets effectivement écrits dans f_handle.

L'appelant peut prendre connaissance de l'espace nécessaire à la structure file_handle en effectuant un appel dans lequel handle->handle_bytes vaut zéro ; dans ce cas, l'appel échoue en renvoyant l'erreur EOVERFLOW et handle->handle_bytes prend pour valeur la taille requise ; l'appelant peut alors utiliser cette information pour allouer une structure ayant la taille convenable (consultez EXEMPLES ci-dessous). Il faut faire attention ici car EOVERFLOW peut indiquer qu'aucun gestionnaire de fichier n'est disponible pour ce nom particulier dans un système de fichiers qui prend normalement en charge la recherche de gestionnaire de fichiers. Ce cas peut se détecter quand l'erreur EOVERFLOW est renvoyée sans que handle_bytes ne soit augmenté.

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.

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, décrits plus bas.

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.

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 ce 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.
• Si pathname est une chaîne non vide contenant un chemin d'accès relatif et si dirfd est le descripteur de fichier d'un répertoire, alors pathname est interprété par rapport au répertoire désigné par dirfd, et un gestionnaire est renvoyé pour le fichier indiqué par le chemin. (Consultez openat(3) si vous souhaitez comprendre à quoi servent les « descripteurs de fichier de répertoires »).
• 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.

L'argument mount_id renvoie un identifiant pour le point de montage du système de fichiers correspondant à pathname. Cet identifiant correspond au premier champ des entrées de /proc/self/mountinfo. L'ouverture du chemin indiqué dans le cinquième champ délivre un descripteur de fichier pour le point de montage ; ce descripteur de fichier peut être utilisé par la suite lors d'un appel à open_by_handle_at(). mount_id est renvoyé tant en cas de succès qu'en cas d'erreur EOVERFLOW de l'appel.

Par défaut, name_to_handle_at() ne déréférence pas pathname s'il s'agit d'un lien symbolique, et donc renvoie un gestionnaire pour le lien lui-même. 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() ne récupère pas un montage quand le composant final du chemin est un point de montage automatique. Quand un système de fichiers gère à la fois les gestionnaires de fichier et les points de montage automatique, un appel name_to_handle_at() sur un point de montage automatique renverra une erreur EOVERFLOW sans augmenter handle_bytes. Cela peut arriver depuis Linux 4.13 avec NFS lors d'un accès à un répertoire sur un système de fichiers séparé du serveur. Dans ce cas, le montage automatique peut être provoqué en ajoutant un « / » à la fin du chemin.

open_by_handle_at()

L'appel système open_by_handle_at() ouvre le fichier auquel handle fait référence, via un indicateur de fichier renvoyé lors d'un précédent appel à name_to_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

Les identifiants de montage dans /proc/self/mountinfo peuvent être réutilisés même lorsque les systèmes de fichiers sont démontés et remontés. Ainsi, l'identifiant de montage renvoyé par name_to_handle_at() (dans *mount_id) ne doit pas être considéré comme un identifiant persistant pour le système de fichiers considéré. Néanmoins, il est possible pour une application d'utiliser l'information fournie dans mountinfo et correspondant à l'identifiant de montage pour en déduire un identifiant persistant.

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 dans /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 <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, "Utilisation : %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");
    /* 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, "Résultat inattendu de name_to_handle_at()\n");
        exit(EXIT_FAILURE);
    }
    /* Ré-alloue la structure file_handle avec la bonne taille. */
    fhsize = sizeof(*fhp) + fhp->handle_bytes;
    fhp = realloc(fhp, fhsize);         /* Copies fhp->handle_bytes */
    if (fhp == NULL)
        err(EXIT_FAILURE, "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)
        err(EXIT_FAILURE, "name_to_handle_at");
    /* Écrit l'identifiant de montage, la taille de l'indicateur et
       l'indicateur vers la sortie standard pour être utilisés
       plus tard par 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);
}

Source du programme : 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);
}