HANDLE(3) Library Functions Manual HANDLE(3)

# [NAME](#NAME)

path\_to\_handle, path\_to\_fshandle, fd\_to\_handle, handle\_to\_fshandle, open\_by\_handle, readlink\_by\_handle, attr\_multi\_by\_handle, attr\_list\_by\_handle, fssetdm\_by\_handle, free\_handle, getparents\_by\_handle, getparentpaths\_by\_handle - file handle operations

# [C SYNOPSIS](#C_SYNOPSIS)

**#include <sys/types.h>**  
**#include <xfs/handle.h>**

**int path\_to\_handle(char \*path, void \*\*hanp, size\_t \*hlen);**

**int path\_to\_fshandle(char \*path, void \*\*hanp, size\_t \*hlen);**

**int fd\_to\_handle(int fd, void \*\*hanp, size\_t \*hlen);**

**int handle\_to\_fshandle(void \*hanp, size\_t hlen, void \*\*fshanp,** **size\_t \*fshlen);**

**int open\_by\_handle(void \*hanp, size\_t hlen, int oflag);**

**int readlink\_by\_handle(void \*hanp, size\_t hlen, void \*buf,** **size\_t bs);**

**int attr\_multi\_by\_handle(void \*hanp, size\_t hlen, void \*buf,** **int rtrvcnt, int flags);**

**int attr\_list\_by\_handle(void \*hanp, size\_t hlen, char \*buf,** **size\_t bufsiz, int flags, struct attrlist\_cursor \*cursor);**

**int fssetdm\_by\_handle(void \*hanp, size\_t hlen, struct fsdmidata** **\*fssetdm);**

**void free\_handle(void \*hanp, size\_t hlen);**

**int getparents\_by\_handle(void \*hanp, size\_t hlen, parent\_t \*buf,** **size\_t bufsiz, parent\_cursor\_t \*cursor, unsigned int \*count,** **unsigned int \*more);**

**int getparentpaths\_by\_handle(void \*hanp, size\_t hlen, parent\_t** **\*buf, size\_t bufsiz, parent\_cursor\_t \*cursor, unsigned int** **\*count, unsigned int \*more);**

# [DESCRIPTION](#DESCRIPTION)

These functions provide a way to perform certain filesystem operations without using a file descriptor to access filesystem objects. They are intended for use by a limited set of system utilities such as backup programs. They are supported only by the XFS filesystem. Link with the **libhandle** library to access these functions.

A handle, *hanp*, uniquely identifies a filesystem object or an entire filesystem. There is one and only one handle per filesystem or filesystem object. Handles consist of some number of bytes. The size of a handle (i.e. the number of bytes comprising it) varies by the type of handle and may vary for different objects of the same type. The content of a handle is opaque to applications. Since handle sizes vary and their contents are opaque, handles are described by two quantities, a pointer (*hanp*) and a size (*hlen*). The size, *hlen*, indicates the number of bytes in the handle which are pointed to by the pointer.

The **path\_to\_handle**() function returns the handle for the object given by the *path* argument. If the final component of the path name is a symbolic link, the handle returned is that of the link itself.

The **path\_to\_fshandle**() function returns the handle for the filesystem in which the object given by the *path* argument resides.

The **fd\_to\_handle**() function returns the handle for the object referenced by the *fd* argument, which must be a valid file descriptor.

The **handle\_to\_fshandle**() function returns the handle for the filesystem in which the object referenced by the handle given by the *hanp* and *hlen* arguments resides.

The **open\_by\_handle**() function opens a file descriptor for the object referenced by a handle. It is analogous and identical to [**open**(2)](/man/os/xfsprogs/open.2) with the exception of accepting handles instead of path names.

The **readlink\_by\_handle**() function returns the contents of a symbolic link referenced by a handle.

The **attr\_multi\_by\_handle**() function manipulates multiple user attributes on a filesystem object. It is analogous and identical to [**attr\_multif**(3)](/man/os/xfsprogs/attr_multif.3) except that a handle is specified instead of a file descriptor.

The **attr\_list\_by\_handle**() function returns the names of the user attributes of a filesystem object. It is analogous and identical to [**attr\_listf**(3)](/man/os/xfsprogs/attr_listf.3) except that a handle is specified instead of a file descriptor.

The **fssetdm\_by\_handle**() function sets the **di\_dmevmask** and **di\_dmstate** fields in an XFS on-disk inode. It is analogous to the **XFS\_IOC\_FSSETDM xfsctl**(3) command, except that a handle is specified instead of a file. This function is not supported on Linux.

The **free\_handle**() function frees the storage allocated for handles returned by the following functions: **path\_to\_handle**(), **path\_to\_fshandle**(), **fd\_to\_handle**(), and **handle\_to\_fshandle**().

The **getparents\_by\_handle**() function returns an array of **parent\_t** structures for each hardlink to the inode represented by the given handle. The parent structure encodes the parent inode number, generation number and the basename of the link. **This function is not operational on Linux.**

The **getparentpaths\_by\_handle**() function is identical to the **getparents\_by\_handle**() function except that instead of returning the basename it returns the path of the link up to the mount point. **This function is also not operational on Linux.**

# [RETURN VALUE](#RETURN_VALUE)

The function **free\_handle**() has no failure indication. The other functions return the value 0 to the calling process if they succeed; otherwise, they return the value -1 and set *errno* to indicate the error.

# [ERRORS](#ERRORS)

[**EACCES**](#EACCES)

Search permission was denied for a component of *path*.

[**EBADF**](#EBADF)

*fd* is not a valid and open file descriptor.

[**EFAULT**](#EFAULT)

An argument pointed to an invalid address.

[**EINVAL**](#EINVAL)

*path* is in a filesystem that does not support these functions.

[**ELOOP**](#ELOOP)

Too many symbolic links were encountered in translating the path name.

[**ENAMETOOLONG**](#ENAMETOOLONG)

A component of *path* or the entire length of *path* exceeds filesystem limits.

[**ENOENT**](#ENOENT)

A component of *path* does not exist.

[**EPERM**](#EPERM)

The caller does not have sufficient privileges.

# [SEE ALSO](#SEE_ALSO)

[**open**(2)](/man/os/xfsprogs/open.2), [**readlink**(2)](/man/os/xfsprogs/readlink.2), [**attr\_multi**(3)](/man/os/xfsprogs/attr_multi.3), [**attr\_list**(3)](/man/os/xfsprogs/attr_list.3), [**xfsctl**(3)](/man/os/xfsprogs/xfsctl.3), [**xfs**(5)](/man/os/xfsprogs/xfs.5).

---

Document: fd_to_handle(3) from xfsprogs 7.2.1-r0 (Chainguard OS)
Source: https://kernel.googlesource.com/pub/scm/fs/xfs/xfsprogs-dev