OPEN_BY_HANDLE_AT(2) Linux Programmer's Manual OPEN_BY_HANDLE_AT(2)NAME
name_to_handle_at - generate a file handle from a pathname
open_by_handle_at - open a file using a file handle
SYNOPSIS
int name_to_handle_at(int dfd, const char * name,
struct file_handle handle, int * mnt_id,
int flag);
int open_by_handle_at(int mountdirfd, struct file_handle handle,
int flags);
DESCRIPTIONopen_by_handle_at() opens the file referenced by the file handle speci‐
fied with handle. This system call uses the file handle that is
returned by the name_to_handle_at() system call. Both system calls can
be considered to split the behavior of the open() system call.
The struct file_handle is defined with the following data structure:
struct file_handle {
unsigned int handle_bytes; /* size of the file handle f_handle */
int handle_type; /* type of the file handle */
void *f_handle; /* file handle */
};
The size of the file handle data structure is specified in handle_bytes
as the actual file handle can have a varying size. The variable of han‐
dle_type specifies how the file within the filesystem is encoded. This
value is set to one of the following values:
enum fid_type {
/*
* The root, or export point, of the filesystem.
* (Never actually passed down to the filesystem.
*/
FILEID_ROOT = 0,
/*
* 32bit inode number, 32 bit generation number.
*/
FILEID_INO32_GEN = 1,
/*
* 32bit inode number, 32 bit generation number,
* 32 bit parent directory inode number.
*/
FILEID_INO32_GEN_PARENT = 2,
/*
* 64 bit object ID, 64 bit root object ID,
* 32 bit generation number.
*/
FILEID_BTRFS_WITHOUT_PARENT = 0x4d,
/*
* 64 bit object ID, 64 bit root object ID,
* 32 bit generation number,
* 64 bit parent object ID, 32 bit parent generation.
*/
FILEID_BTRFS_WITH_PARENT = 0x4e,
/*
* 64 bit object ID, 64 bit root object ID,
* 32 bit generation number,
* 64 bit parent object ID, 32 bit parent generation,
* 64 bit parent root object ID.
*/
FILEID_BTRFS_WITH_PARENT_ROOT = 0x4f,
/*
* 32 bit block number, 16 bit partition reference,
* 16 bit unused, 32 bit generation number.
*/
FILEID_UDF_WITHOUT_PARENT = 0x51,
/*
* 32 bit block number, 16 bit partition reference,
* 16 bit unused, 32 bit generation number,
* 32 bit parent block number, 32 bit parent generation number
*/
FILEID_UDF_WITH_PARENT = 0x52,
/*
* 64 bit checkpoint number, 64 bit inode number,
* 32 bit generation number.
*/
FILEID_NILFS_WITHOUT_PARENT = 0x61,
/*
* 64 bit checkpoint number, 64 bit inode number,
* 32 bit generation number, 32 bit parent generation.
* 64 bit parent inode number.
*/
FILEID_NILFS_WITH_PARENT = 0x62,
};
The actual file handle held in the member variable of f_handle must be
treated as an opaque value by the calling user space application. The
contents of this handle value may differ depending on the underlying
file system.
The system call name_to_handle_at() performs the lookup of the
requested file system object and returns the file handle to that
object. If the pathname given in name is relative, then it is inter‐
preted relative to the directory referred to by the file descriptor dfd
(rather than relative to the current working directory of the call‐
ing process). When dfd not NULL, the same principle as outlined for the
openat() system call is applied. Using the parameter handle the calling
process must specify the maximum size of the file handle. When the ker‐
nel generated the file handle, handle is filled with the file handle
type and the actual file handle. The size of the actual file handle
provided by the kernel is set in handle.handle_bytes. The parameter
mnt_id is filled by the kernel with the mount id of the file system
containing the file. The flag parameter allows the calling process to
specify whether to follow a symlink (using AT_SYMLINK_FOLLOW) or not
(using AT_EMPTY_PATH).
The system call open_by_handle_at() opens the file system object
pointed to by the file handle handle. The parameter of mountdirfd
specifies the file descriptor of the directory used as a base for the
file system object lookup. The file handle is decoded relative to that
directory. The flags parameter can be used to specify the same file
open flags as documented for the open() system call.
RETURN VALUE
On success, open_by_handle_at returns a new file descriptor. On error,
-1 is returned, and errno is set to indicate the error.
On success, name_to_handle_at returns 0. On error, -1 is returned, and
errno is set to indicate the error.
ERRORSopen_by_handle_at() returns the same errors as documented for open().
In addition, the following error conditions exist.
EPERM The calling process does not possess the CAP_DAC_READ_SEARCH
capability.
EFAULT The file handle data stucture or the opaque file handle cannot
be retrieved by the kernel.
EINVAL The size of the file handle specified in handle.handle_bytes is
too large.
ENOMEM The kernel has insufficient memory for performing the operation.
name_to_handle_at() returns the same errors as documented for open().
In addition, the following error conditions exist.
EFAULT The file handle data stucture cannot be retrieved by the kernel.
EINVAL The size of the file handle specified in handle.handle_bytes is
too large.
ENOMEM The kernel has insufficient memory for performing the operation.
EINVAL An invalid value was specified in the flag argument.
EOVERFLOW
The size of the file handle exceeds the size specified by the
calling process in handle.handle_bytes.
EFAULT The kernel is unable to copy the handle data structure to user
space.
CONFORMING TO
These system calls are Linux-specific and appeared in the Linux kernel
2.6.39.
NOTES
The system calls, the file handle data structure, as well as the file
handle types are not yet exported via glibc or another library. The
system calls must be invoked using the syscall() function.
SEE ALSOopen(2), openat(2). syscall(2)Linux 2011-09-09 OPEN_BY_HANDLE_AT(2)