name_to_handle_at()¶

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] */
};

f_handle で返されるハンドルを保持するのに十分な大きさの構造体を確保するのは、 呼び出し元が責任をもって行う必要がある。 呼び出し前に、 handle_bytes フィールドは f_handle 用に格納されたサイズで初期化すべきである (<fcntl.h> で定義されている定数 MAX_HANDLE_SZ でファイルハンドルの最大サイズが規定されている)。 呼び出しが成功でリターンする際、 handle_bytes フィールドは f_handle に実際に書き込まれたバイト数に更新される。

呼び出し元では、 handle->handle_bytes を 0 に設定して呼び出しを行うことで、 file_handle 構造体に必要なサイズを知ることができる。 この場合、 この呼び出しはエラー EOVERFLOW で失敗し、 handle->handle_bytes に必要なサイズが設定される。 呼び出し元はこの情報を使って、正しいサイズの構造体を割り当てることができる (下記の「例」を参照)。

handle_bytes フィールドを使用する以外は、 呼び出し元は file_handle 構造体の内容を意識せずに扱うべきである。 フィールド handle_type と f_handle は後で open_by_handle_at() を呼び出す場合にだけ必要である。

flags 引き数は、 下記の AT_EMPTY_PATH と AT_SYMLINK_FOLLOW のうち 0 個以上の論理和を取って構成されるビットマスクである。

引き数 pathname と dirfd はその組み合わせでハンドルを取得するファイルを指定する。 以下の 4 つのパターンがある。

• pathname が空でない文字列で絶対パス名を含む場合、 このパス名が参照するファイルに対するハンドルが返される。
• pathname が相対パスが入った空でない文字列で、 dirfd が特別な値 AT_FDCWD の場合、 pathname は呼び出し元のカレントワーキングディレクトリに対する相対パスと解釈され、 そのファイルに対するハンドルが返される。
• pathname が相対パスが入った空でない文字列で、 dirfd がディレクトリを参照するファイルディスクリプターの場合、 pathname は dirfd が参照するディレクトリに対する相対パスと解釈され、 そのファイルを参照するハンドルが返される。(なぜ「ディレクトリファイルディスクリプター」が役に立つのかについては openat(2) を参照。)
• pathname が空の文字列で flags に AT_EMPTY_PATH が指定されている場合、 dirfd には任意の種別のファイルを参照するオープンされたファイルディスクリプターか AT_FDCWD (カレントワーキングディレクトリを意味する) を指定でき、 dirfd が参照するファイルに対するハンドルが返される。

mount_id 引き数は、 pathname に対応するファイルシステムのマウントの識別子を返す。 この識別子は /proc/self/mountinfo のいずれかのレコードの最初のフィールドに対応する。 対応するレコードの 5 番目のフィールドのパス名をオープンすると、 このマウントポイントのファイルディスクリプターが得られる。 このファイルディスクリプターはこの後の open_by_handle_at() の呼び出しで使用できる。

デフォルトでは、 name_to_handle_at() は pathname がシンボリックリンクの場合にその展開 (dereference) を行わず、 リンク自身に対するハンドルを返す。 AT_SYMLINK_FOLLOW が flags に指定されると、 pathname がシンボリックリンクの場合にリンクの展開が行われる (リンクが参照するファイルに対するハンドルが返される)。

open_by_handle_at()¶

mount_fd 引き数は、 handle がそのファイルシステムに関連すると解釈されるマウントされたファイルシステム内の任意のオブジェクト (ファイル、 ディレクトリなど) のファイルディスクリプターである。 特別な値 AT_FDCWD も指定できる。 この値は呼び出し元のカレントワーキングディレクトリを意味する。

引き数 flags は open(2) と同じである。 handle がシンボリックリンクを参照している場合、 呼び出し元は O_PATH フラグを指定しなければならず、 そのシンボリックリンクは展開されない。 O_NOFOLLOW が指定された場合は、 O_NOFOLLOW は無視される。

open_by_handle_at() を呼び出すには、 呼び出し元が CAP_DAC_READ_SEARCH ケーパビリティーを持っていなければならない。

永続的なファイルシステム ID の取得¶

例えば、 mountinfo レコードの 5 番目のフィールドのデバイス名を使って、 /dev/disks/by-uuid のシンボリックリンク経由で対応するデバイス UUID を検索できる。 (UUID を取得するもっと便利な方法は libblkid(3) ライブラリを使用することである。) そのプロセスは、逆に、 この UUID を使ってデバイス名を検索し、 対応するマウントポイントを取得することで、 open_by_handle_at() で使用する mount_fd 引き数を生成することができる。

プログラムのソース: 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];
    /* file_handle 構造体を確保する */
    fhsize = sizeof(*fhp);
    fhp = malloc(fhsize);
    if (fhp == NULL)
        errExit("malloc");
    /* name_to_handle_at() を最初に呼び出して
       ファイルハンドルに必要なサイズを入手する */
    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);
    }
    /* file_handle 構造体を正しいサイズに確保し直す */
    fhsize = sizeof(struct file_handle) + fhp->handle_bytes;
    fhp = realloc(fhp, fhsize);         /* Copies fhp->handle_bytes */
    if (fhp == NULL)
        errExit("realloc");
    /* コマンドラインで指定されたパス名からファイルハンドルを取得 */
    if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == -1)
        errExit("name_to_handle_at");
    /* t_open_by_handle_at.c で後で再利用できるように、マウント ID、
       ファイルハンドルのサイズ、ファイルハンドルを標準出力に書き出す */
    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);
}

プログラムのソース: 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)
/* /proc/self/mountinfo をスキャンして、マウント ID が 'mount_id' に
   一致する行を探す。 (もっと簡単な方法は 'util-linux' プロジェクト
   が提供する 'libmount' ライブラリをインストールして使うことである)
   対応するマウントパスをオープンし、得られたファイルディスクリプターを返す。 */
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, 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);
    }
    /* マウント ID とファイルハンドル情報が入った標準入力:
         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);
    /* handle_bytes があれば、
       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);
    /* マウントポイントのファイルディスクリプターを取得する。
       取得は、コマンドラインで指定されたパス名をオープンするか、
       /proc/self/mounts をスキャンして標準入力から受け取った
       'mount_id' に一致するマウントを探すことで行う。 */
    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");
    /* ハンドルとマウントポイントを使ってファイルをオープンする */
    fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
    if (fd == -1)
        errExit("open_by_handle_at");
    /* そのファイルからバイトを読み出す */
    nread = read(fd, buf, sizeof(buf));
    if (nread == -1)
        errExit("read");
    printf("Read %zd bytes\n", nread);
    exit(EXIT_SUCCESS);
}