---
name: "path_to_handle"
section: "3"
platform: "linux"
package: "xfsprogs"
version: "7.2.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/path_to_handle"
---

# path\_to\_handle(3)

file handle operations

## 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

**#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

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)](/open/2.md) 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)](/attr_multif/3.md) 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)](/attr_listf/3.md) 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

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

- **EACCES**

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

- **EBADF**

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

- **EFAULT**

  An argument pointed to an invalid address.

- **EINVAL**

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

- **ELOOP**

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

- **ENAMETOOLONG**

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

- **ENOENT**

  A component of *path* does not exist.

- **EPERM**

  The caller does not have sufficient privileges.

## SEE ALSO

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