-'\" t -*- coding: UTF-8 -*-
.\" Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH OPEN_BY_HANDLE_AT 2 2014-03-24 "Linux" "Linux Programmer's Manual"
+.TH OPEN_BY_HANDLE_AT 2 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
name_to_handle_at, open_by_handle_at \- obtain handle
for a pathname and open file via a handle
.SH SYNOPSIS
.nf
-.B #define _GNU_SOURCE
+.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/types.h>
.B #include <sys/stat.h>
.B #include <fcntl.h>
-
+.PP
.BI "int name_to_handle_at(int " dirfd ", const char *" pathname ,
.BI " struct file_handle *" handle ,
.BI " int *" mount_id ", int " flags );
-
+.PP
.BI "int open_by_handle_at(int " mount_fd ", struct file_handle *" handle ,
.BI " int " flags );
.fi
The file handle is returned via the argument
.IR handle ,
which is a pointer to a structure of the following form:
-
+.PP
.in +4n
-.nf
+.EX
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] */
};
-.fi
+.EE
.in
.PP
It is the caller's responsibility to allocate the structure
.BR MAX_HANDLE_SZ ,
defined in
.IR <fcntl.h> ,
-specifies the maximum possible size for a file handle.)
+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
.IR handle_bytes
field is updated to contain the number of bytes actually written to
.IR f_handle .
-
+.PP
The caller can discover the required size for the
.I file_handle
structure by making a call in which
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
+.BR 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
+.B EOVERFLOW
+error is returned without
+.I handle_bytes
+being increased.
+.PP
Other than the use of the
.IR handle_bytes
field, the caller should treat the
.IR f_handle
fields are needed only by a subsequent call to
.BR open_by_handle_at ().
-
+.PP
+The
+.I flags
+argument is a bit mask constructed by ORing together zero or more of
+.BR AT_EMPTY_PATH
+and
+.BR AT_SYMLINK_FOLLOW ,
+described below.
+.PP
Together, the
.I pathname
and
.I dirfd
-arguments identify the file for which a handle is to obtained.
+arguments identify the file for which a handle is to be obtained.
There are four distinct cases:
.IP * 3
If
.IR dirfd ,
and a handle is returned for the file to which it refers.
(See
-.BR openat (3)
+.BR openat (2)
for an explanation of why "directory file descriptors" are useful.)
.IP *
If
descriptor for the mount point;
that file descriptor can be used in a subsequent call to
.BR open_by_handle_at ().
-
-The
-.I flags
-argument is a bit mask constructed by ORing together
-zero or more of the following value:
-.TP
-.B AT_EMPTY_PATH
-Allow
-.I pathname
-to be an empty string.
-See above.
-(which may have been obtained using the
-.BR open (2)
-.B O_PATH
-flag).
-.TP
-.B AT_SYMLINK_FOLLOW
+.I mount_id
+is returned both for a successful call and for a call that results
+in the error
+.BR EOVERFLOW .
+.PP
By default,
.BR name_to_handle_at ()
does not dereference
.I pathname
-if it is a symbolic link.
-The flag
+if it is a symbolic link, and thus returns a handle for the link itself.
+If
.B AT_SYMLINK_FOLLOW
-can be specified in
-.I flags
-to cause
+is specified in
+.IR flags ,
.I pathname
-to be dereferenced if it is a symbolic link.
+is dereferenced if it is a symbolic link
+(so that the call returns a handle for the file referred to by the link).
+.PP
+.BR 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
+.BR name_to_handle_at ()
+call on an automount point will return with error
+.BR EOVERFLOW
+without having increased
+.IR handle_bytes .
+This can happen since Linux 4.13
+.\" commit 20fa19027286983ab2734b5910c4a687436e0c31
+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.
.SS open_by_handle_at()
The
.BR open_by_handle_at ()
.IR handle ,
a file handle returned by a previous call to
.BR name_to_handle_at ().
-
+.PP
The
.IR mount_fd
argument is a file descriptor for any object (file, directory, etc.)
The special value
.B AT_FDCWD
can be specified, meaning the current working directory of the caller.
-
+.PP
The
.I flags
argument
is as for
.BR open (2).
-.\" FIXME: Confirm that the following is intended behavior.
-.\" (It certainly seems to be the behavior, from experimenting.)
If
.I handle
refers to a symbolic link, the caller must specify the
.B O_PATH
-flag, and the symbolic link is not dereferenced (the
+flag, and the symbolic link is not dereferenced; the
.B O_NOFOLLOW
-flag, if specified, is ignored).
-
+flag, if specified, is ignored.
+.PP
The caller must have the
.B CAP_DAC_READ_SEARCH
capability to invoke
and
.BR open_by_handle_at ()
returns a nonnegative file descriptor.
-
+.PP
In the event of an error, both system calls return \-1 and set
.I errno
to indicate the cause of the error.
can fail for the same errors as
.BR openat (2).
In addition, they can fail with the errors noted below.
-
+.PP
.BR name_to_handle_at ()
can fail with the following errors:
.TP
+.B EFAULT
+.IR pathname ,
+.IR mount_id ,
+or
+.IR handle
+points outside your accessible address space.
+.TP
.B EINVAL
.I flags
includes an invalid bit value.
.TP
.B EINVAL
-.IR handle_bytes\->handle_bytes
+.IR handle\->handle_bytes
is greater than
.BR MAX_HANDLE_SZ .
.TP
The file descriptor supplied in
.I dirfd
does not refer to a directory,
-and it it is not the case that both
+and it is not the case that both
.I flags
includes
.BR AT_EMPTY_PATH
.IR mount_fd
is not an open file descriptor.
.TP
+.B EFAULT
+.IR handle
+points outside your accessible address space.
+.TP
.B EINVAL
.I handle->handle_bytes
is greater than
or is equal to zero.
.TP
.B ELOOP
-.\" FIXME (see earlier FIXME). Is this the intended behavior?
.I handle
refers to a symbolic link, but
.B O_PATH
.B ESTALE
The specified
.I handle
-is no longer valid.
+is not valid.
+This error will occur if, for example, the file has been deleted.
.SH VERSIONS
These system calls first appeared in Linux 2.6.39.
+Library support is provided in glibc since version 2.14.
.SH CONFORMING TO
These system calls are nonstandard Linux extensions.
+.PP
+FreeBSD has a broadly similar pair of system calls in the form of
+.BR getfh ()
+and
+.BR openfh ().
.SH NOTES
A file handle can be generated in one process using
.BR name_to_handle_at ()
and later used in a different process that calls
.BR open_by_handle_at ().
-
-Not all filesystem types support the translation of pathnames to
-file handles.
-.\" FIXME NeilBrown noted:
-.\" ESTALE is also returned if the filesystem does not support
-.\" file-handle -> file mappings.
-.\" On filesystems which don't provide export_operations (/sys /proc
-.\" ubifs romfs cramfs nfs coda ... several others) name_to_handle_at
-.\" will produce a generic handle using the 32 bit inode and 32 bit
-.\" i_generation. open_by_name_at given this (or any) filehandle
-.\" will fail with ESTALE.
-.\" However, on /proc and /sys, at least, name_to_handle_at() fails with
-.\" EOPNOTSUPP. Are there really filesystems that can deliver ESTALE (the
-.\" same error as for an invalid file handle) in the above circumstances?
-
+.PP
+Some filesystem don't support the translation of pathnames to
+file handles, for example,
+.IR /proc ,
+.IR /sys ,
+and various network filesystems.
+.PP
A file handle may become invalid ("stale") if a file is deleted,
or for other filesystem-specific reasons.
Invalid handles are notified by an
.B ESTALE
error from
-.BR open_by_name_at ().
-
+.BR open_by_handle_at ().
+.PP
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.
.\" "Open by handle" - Jonathan Corbet, 2010-02-23
This sort of functionality allows a user-space file server to operate in
a stateless fashion with respect to the files it serves.
-
+.PP
If
.I pathname
refers to a symbolic link and
.IR /proc/self/mountinfo
can be reused as filesystems are unmounted and mounted.
Therefore, the mount ID returned by
-.BR name_to_handle_at (3)
+.BR name_to_handle_at ()
(in
.IR *mount_id )
should not be treated as a persistent identifier
.I mountinfo
record that corresponds to the mount ID
to derive a persistent identifier.
-
+.PP
For example, one can use the device name in the fifth field of the
.I mountinfo
record to search for the corresponding device UUID via the symbolic links in
in order to produce the
.IR mount_fd
argument used by
-.BR open_by_name_at ().
+.BR open_by_handle_at ().
.SH EXAMPLE
The two programs below demonstrate the use of
.BR name_to_handle_at ()
.BR name_to_handle_at ()
to obtain the file handle and mount ID
for the file specified in its command-line argument;
-the handle and ID are written to standard output.
-
+the handle and mount ID are written to standard output.
+.PP
The second program
.RI ( t_open_by_handle_at.c )
reads a mount ID and file handle from standard input.
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.)
-
+.PP
The following shell session demonstrates the use of these two programs:
-
+.PP
.in +4n
-.nf
-$ \fBecho 'Kannst du bitte überlegen?' > cecilia.txt\fP
+.EX
+$ \fBecho 'Can you please think about it?' > cecilia.txt\fP
$ \fB./t_name_to_handle_at cecilia.txt > fh\fP
$ \fB./t_open_by_handle_at < fh\fP
open_by_handle_at: Operation not permitted
$ \fBsudo ./t_open_by_handle_at < fh\fP # Need CAP_SYS_ADMIN
-Read 28 bytes
+Read 31 bytes
$ \fBrm cecilia.txt\fP
-.fi
+.EE
.in
-
+.PP
Now we delete and (quickly) re-create the file so that
it has the same content and (by chance) the same inode.
Nevertheless,
.BR open_by_handle_at ()
+.\" Christoph Hellwig: That's why the file handles contain a generation
+.\" counter that gets incremented in this case.
recognizes that the original file referred to by the file handle
no longer exists.
-
+.PP
.in +4n
-.nf
-$ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Display inode number
+.EX
+$ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number
4072121
$ \fBrm cecilia.txt\fP
-$ \fBecho 'Kannst du bitte überlegen?' > cecilia.txt\fP
-$ \fBstat \-\-printf="%i\\n" cecilia.txt\fP # Check inode number
+$ \fBecho 'Can you please think about it?' > cecilia.txt\fP
+$ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Check inode number
4072121
$ \fBsudo ./t_open_by_handle_at < fh\fP
open_by_handle_at: Stale NFS file handle
-.fi
+.EE
.in
.SS Program source: t_name_to_handle_at.c
\&
-.nf
+.EX
#define _GNU_SOURCE
#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>
#include <string.h>
-#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
} while (0)
int
main(int argc, char *argv[])
{
struct file_handle *fhp;
- int mount_id, fhsize, s;
+ int mount_id, fhsize, flags, dirfd, j;
+ char *pathname;
- if (argc < 2 || strcmp(argv[1], "\-\-help") == 0) {
- fprintf(stderr, "Usage: %s pathname\\n", argv[0]);
+ if (argc != 2) {
+ fprintf(stderr, "Usage: %s pathname\en", argv[0]);
exit(EXIT_FAILURE);
}
+ pathname = argv[1];
+
/* Allocate file_handle structure */
- fhsize = sizeof(struct file_handle *);
+ 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;
- s = name_to_handle_at(AT_FDCWD, argv[1], fhp, &mount_id, 0);
- if (s != \-1 || errno != EOVERFLOW) {
- fprintf(stderr, "Unexpected result from name_to_handle_at()\\n");
+ if (name_to_handle_at(dirfd, pathname, fhp,
+ &mount_id, flags) != \-1 || errno != EOVERFLOW) {
+ fprintf(stderr, "Unexpected result from name_to_handle_at()\en");
exit(EXIT_FAILURE);
}
/* Get file handle from pathname supplied on command line */
- if (name_to_handle_at(AT_FDCWD, argv[1], fhp, &mount_id, 0) == \-1)
+ 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 */
- if (write(STDOUT_FILENO, &mount_id, sizeof(int)) != sizeof(int) ||
- write(STDOUT_FILENO, &fhsize, sizeof(int)) != sizeof(int) ||
- write(STDOUT_FILENO, fhp, fhsize) != fhsize) {
- fprintf(stderr, "Write failure\\n");
- exit(EXIT_FAILURE);
- }
+ printf("%d\en", 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("\en");
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SS Program source: t_open_by_handle_at.c
\&
-.nf
+.EX
#define _GNU_SOURCE
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <string.h>
-#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
} while (0)
/* Scan /proc/self/mountinfo to find the line whose mount ID matches
char *linep;
size_t lsize;
char mount_path[PATH_MAX];
- int fmnt_id, fnd, nread;
+ int mi_mount_id, found;
+ ssize_t nread;
FILE *fp;
- fp = fopen("/proc/self/mountinfo", "r");
+ fp = fopen("/proc/self/mountinfo", "r");
if (fp == NULL)
errExit("fopen");
- for (fnd = 0; !fnd ; ) {
- linep = NULL;
+ found = 0;
+ linep = NULL;
+ while (!found) {
nread = getline(&linep, &lsize, fp);
if (nread == \-1)
break;
- nread = sscanf(linep, "%d %*d %*s %*s %s", &fmnt_id, mount_path);
+ nread = sscanf(linep, "%d %*d %*s %*s %s",
+ &mi_mount_id, mount_path);
if (nread != 2) {
- fprintf(stderr, "Bad sscanf()\\n");
+ fprintf(stderr, "Bad sscanf()\en");
exit(EXIT_FAILURE);
}
- free(linep);
-
- if (fmnt_id == mount_id)
- fnd = 1;
+ if (mi_mount_id == mount_id)
+ found = 1;
}
+ free(linep);
fclose(fp);
- if (!fnd) {
- fprintf(stderr, "Could not find mount point\\n");
+ if (!found) {
+ fprintf(stderr, "Could not find mount point\en");
exit(EXIT_FAILURE);
}
- return open(mount_path, O_RDONLY | O_DIRECTORY);
+ return open(mount_path, O_RDONLY);
}
int
main(int argc, char *argv[])
{
struct file_handle *fhp;
- int mount_id, fd, mount_fd, fhsize;
+ int mount_id, fd, mount_fd, handle_bytes, j;
ssize_t nread;
-#define BSIZE 1000
- char buf[BSIZE];
+ char buf[1000];
+#define LINE_SIZE 100
+ char line1[LINE_SIZE], line2[LINE_SIZE];
+ char *nextp;
- if (argc > 1 && strcmp(argv[1], "\-\-help") == 0) {
- fprintf(stderr, "Usage: %s [mount\-dir]]\\n",
- argv[0]);
+ if ((argc > 1 && strcmp(argv[1], "\-\-help") == 0) || argc > 2) {
+ fprintf(stderr, "Usage: %s [mount\-path]\en", argv[0]);
exit(EXIT_FAILURE);
}
- /* Read data produced by t_name_to_handle_at.c */
+ /* Standard input contains mount ID and file handle information:
- if (read(STDIN_FILENO, &mount_id, sizeof(int)) != sizeof(int))
- errExit("read");
+ Line 1: <mount_id>
+ Line 2: <handle_bytes> <handle_type> <bytes of handle in hex>
+ */
- if (read(STDIN_FILENO, &fhsize, sizeof(int)) != sizeof(int))
- errExit("read");
+ if ((fgets(line1, sizeof(line1), stdin) == NULL) ||
+ (fgets(line2, sizeof(line2), stdin) == NULL)) {
+ fprintf(stderr, "Missing mount_id / file handle\en");
+ exit(EXIT_FAILURE);
+ }
- fhp = malloc(fhsize);
+ 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");
- if (read(STDIN_FILENO, fhp, fhsize) != fhsize)
- errExit("read");
+ 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 \(aqmount_id\(aq
- obtained by name_to_handle_at() (in t_name_to_handle_at.c) */
+ that we received from stdin. */
if (argc > 1)
- mount_fd = open(argv[1], O_RDONLY | O_DIRECTORY);
+ 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 name using handle and mount point */
+ /* Open file using handle and mount point */
fd = open_by_handle_at(mount_fd, fhp, O_RDONLY);
if (fd == \-1)
/* Try reading a few bytes from the file */
- nread = read(fd, buf, BSIZE);
+ nread = read(fd, buf, sizeof(buf));
if (nread == \-1)
errExit("read");
- printf("Read %ld bytes\\n", (long) nread);
+
+ printf("Read %zd bytes\en", nread);
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SH SEE ALSO
-.BR blkid (1),
-.BR findfs (1),
.BR open (2),
.BR libblkid (3),
+.BR blkid (8),
+.BR findfs (8),
.BR mount (8)
-
+.PP
The
.I libblkid
and
.I libmount
-documentation under the latest
+documentation in the latest
.I util-linux
release at
-.UR https://www.kernel.org/pub/linux/utils/util-linux/
+.UR https://www.kernel.org/pub/linux/utils/util\-linux/
.UE
projects / thirdparty / man-pages.git / blobdiff