FSGETPATH(2)

NAME
fsgetpath - get the path associated with filesystem node identifier (inode number/link id/object id)

SYNOPSIS
#include <sys/attr.h>
#include <sys/fsgetpath.h>

ssize_t
fsgetpath(char * restrict_buf, size_t buflen, fsid_t * fsid, uint64_t obj_id);

DESCRIPTION
The fsgetpath() function returns the path in a caller provided buffer restrict_buf of length indicated by buflen associated with a filesystem object identified by fsid and obj_id. fsid is a pointer to a structure which identifies a filesystem to which the object belongs. It is obtained by the value returned for ATTR_CMN_FSID in a previous call to getattrlist(2) or the f_fsid field of the statfs structure returned by statfs(2). obj_id can be any one of of a object identifier i.e. ATTR_CMN_FILEID returned by getattrlist(2) or st_ino field of the stat structure returned by stat(2) or a link id returned in ATTR_CMNEXT_LINKID by a previous call to getattrlist(2). Using a linkid will result in a more accurate path in case the filesystem object is a hard link. If a inode number is passed and the object is a hard link, any one of the multiple paths to that filesystem object may be returned.

RETURN VALUES
Upon successful completion, fsgetpath() returns the length of the path including the null terminator. Otherwise, a value of -1 is returned and errno is set to indicate the error.

COMPATIBILITY
Not all volumes support fsgetpath(). A volume can be tested for fsgetpath() support by using getattrlist(2) to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_FMT_PATH_FROM_ID flag.

ERRORS
The fsgetpath() function will fail if:

[EACCES]
    Read permissions are denied on any component of the pathname.

[ENOTSUP]
    The underlying filesystem does not support this call.

[EINVAL]
    buflen is larger than PAGE_SIZE

[EIO]
    An I/O error occurred while reading from the file system.

[EPERM]
    The calling process does not have appropriate privileges.

[ENOENT]
    The Filesystem object does not exist.

[EFAULT]
    restrict_buf points to memory not valid in the callers address space.

[ENOSPC]
    restrict_buf is not large enough to hold the path.

SEE ALSO
getattrlist(2) statfs(2) stat(2)

HISTORY
The fsgetpath() function call appeared in macOS version 10.13