Section (2) open_by_handle_at
Name
name_to_handle_at, open_by_handle_at — obtain handle for a pathname and open file via a handle
Synopsis
#define _GNU_SOURCE /* See feature_test_macros(7) */ #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h>
int
name_to_handle_at( |
int dirfd, |
const char *pathname, | |
struct file_handle *handle, | |
int *mount_id, | |
int flags) ; |
int
open_by_handle_at( |
int mount_fd, |
struct file_handle *handle, | |
int flags) ; |
DESCRIPTION
The name_to_handle_at
() and
open_by_handle_at
() system
calls split the functionality of openat(2) into two parts:
name_to_handle_at
() returns an
opaque handle that corresponds to a specified file;
open_by_handle_at
() opens the
file corresponding to a handle returned by a previous call to
name_to_handle_at
() and returns
an open file descriptor.
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_zsingle_quotesz_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.
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 anddirfd
has the special valueAT_FDCWD
, thenpathname
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 anddirfd
is a file descriptor referring to a directory, thenpathname
is interpreted relative to the directory referred to bydirfd
, 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 andflags
specifies the valueAT_EMPTY_PATH
, thendirfd
can be an open file descriptor referring to any type of file, orAT_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
().
RETURN VALUE
On success, name_to_handle_at
() returns 0, and
open_by_handle_at
() returns a
nonnegative file descriptor.
In the event of an error, both system calls return
−1 and set errno
to
indicate the cause of the error.
ERRORS
name_to_handle_at
() and
open_by_handle_at
() can fail
for the same errors as openat(2). In addition,
they can fail with the errors noted below.
name_to_handle_at
() can fail
with the following errors:
- EFAULT
-
pathname
,mount_id
, orhandle
points outside your accessible address space. - EINVAL
-
flags
includes an invalid bit value. - EINVAL
-
handle−>handle_bytes
is greater thanMAX_HANDLE_SZ
. - ENOENT
-
pathname
is an empty string, butAT_EMPTY_PATH
was not specified inflags
. - ENOTDIR
-
The file descriptor supplied in
dirfd
does not refer to a directory, and it is not the case that bothflags
includesAT_EMPTY_PATH
andpathname
is an empty string. - EOPNOTSUPP
-
The filesystem does not support decoding of a pathname to a file handle.
- EOVERFLOW
-
The
handle->handle_bytes
value passed into the call was too small. When this error occurs,handle->handle_bytes
is updated to indicate the required size for the handle.
open_by_handle_at
() can fail
with the following errors:
- EBADF
-
mount_fd
is not an open file descriptor. - EFAULT
-
handle
points outside your accessible address space. - EINVAL
-
handle->handle_bytes
is greater thanMAX_HANDLE_SZ
or is equal to zero. - ELOOP
-
handle
refers to a symbolic link, butO_PATH
was not specified inflags
. - EPERM
-
The caller does not have the
CAP_DAC_READ_SEARCH
capability. - ESTALE
-
The specified
handle
is not valid. This error will occur if, for example, the file has been deleted.
VERSIONS
These system calls first appeared in Linux 2.6.39. Library support is provided in glibc since version 2.14.
CONFORMING TO
These system calls are nonstandard Linux extensions.
FreeBSD has a broadly similar pair of system calls in the
form of getfh
() and
openfh
().
NOTES
A file handle can be generated in one process using
name_to_handle_at
() and later
used in a different process that calls open_by_handle_at
().
Some filesystem don_zsingle_quotesz_t support the translation of pathnames
to file handles, for example, /proc
, /sys
,
and various network filesystems.
A file handle may become invalid (stale) if a file is
deleted, or for other filesystem-specific reasons. Invalid
handles are notified by an ESTALE error from open_by_handle_at
().
These system calls are designed for use by user-space file servers. For example, a user-space NFS server might generate a file handle and pass it to an NFS client. Later, when the client wants to open the file, it could pass the handle back to the server. This sort of functionality allows a user-space file server to operate in a stateless fashion with respect to the files it serves.
If pathname
refers
to a symbolic link and flags
does not specify
AT_SYMLINK_FOLLOW
, then
name_to_handle_at
() returns a
handle for the link (rather than the file to which it
refers). The process receiving the handle can later perform
operations on the symbolic link by converting the handle to a
file descriptor using open_by_handle_at
() with the O_PATH
flag, and then passing the file
descriptor as the dirfd
argument in system calls
such as readlinkat(2) and fchownat(2).
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
().
EXAMPLE
The two programs below demonstrate the use of name_to_handle_at
() and open_by_handle_at
(). The first program
(t_name_to_handle_at.c
) uses
name_to_handle_at
() to obtain
the file handle and mount ID for the file specified in its
command-line argument; the handle and mount ID are written to
standard output.
The second program (t_open_by_handle_at.c
) reads a mount ID and
file handle from standard input. The program then employs
open_by_handle_at
() to open the
file using that handle. If an optional command-line argument
is supplied, then the mount_fd
argument for
open_by_handle_at
() is obtained
by opening the directory named in that argument. Otherwise,
mount_fd
is obtained
by scanning /proc/self/mountinfo
to find a record whose
mount ID matches the mount ID read from standard input, and
the mount directory specified in that record is opened.
(These programs do not deal with the fact that mount IDs are
not persistent.)
The following shell session demonstrates the use of these two programs:
$ echo _zsingle_quotesz_Can you please think about it?_zsingle_quotesz_ > cecilia.txt $ ./t_name_to_handle_at cecilia.txt > fh $ ./t_open_by_handle_at < fh open_by_handle_at: Operation not permitted $ sudo ./t_open_by_handle_at < fh # Need CAP_SYS_ADMIN Read 31 bytes $ rm cecilia.txt
Now we delete and (quickly) re-create the file so that it
has the same content and (by chance) the same inode.
Nevertheless, open_by_handle_at
() recognizes that the
original file referred to by the file handle no longer
exists.
$ stat −−printf=%i cecilia.txt # Display inode number 4072121 $ rm cecilia.txt $ echo _zsingle_quotesz_Can you please think about it?_zsingle_quotesz_ > cecilia.txt $ stat −−printf=%i cecilia.txt # Check inode number 4072121 $ sudo ./t_open_by_handle_at < fh open_by_handle_at: Stale NFS file handle
Program source: 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 , 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() ); exit(EXIT_FAILURE); } /* Reallocate file_handle structure with correct size */ fhsize = sizeof(struct file_handle) + 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 , 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( ); exit(EXIT_SUCCESS); }
Program source: 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) /* Scan /proc/self/mountinfo to find the line whose mount ID matches _zsingle_quotesz_mount_id_zsingle_quotesz_. (An easier way to do this is to install and use the _zsingle_quotesz_libmount_zsingle_quotesz_ library provided by the _zsingle_quotesz_util−linux_zsingle_quotesz_ 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() ); exit(EXIT_FAILURE); } if (mi_mount_id == mount_id) found = 1; } free(linep); fclose(fp); if (!found) { fprintf(stderr, Could not find mount point ); 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] , 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 ); 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(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); /* 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 _zsingle_quotesz_mount_id_zsingle_quotesz_ 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 , nread); exit(EXIT_SUCCESS); }
SEE ALSO
open(2), libblkid(3), blkid(8), findfs(8), mount(8)
The libblkid
and
libmount
documentation in the latest util-linux
release at
https://www.kernel.org/pub/linux/utils/util-linux/
COLOPHON
This page is part of release 5.04 of the Linux man-pages
project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
Copyright (c) 2014 by Michael Kerrisk <mtk.manpagesgmail.com> %%%LICENSE_START(VERBATIM) Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Since the Linux kernel and libraries are constantly changing, this manual page may be incorrect or out-of-date. The author(s) assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. The author(s) may not have taken the same level of care in the production of this manual, which is licensed free of charge, as they might when working professionally. Formatted or processed versions of this manual, if unaccompanied by the source, must acknowledge the copyright and authors of this work. %%%LICENSE_END |