documents: fsgetpath
FSGETPATH(2) System Calls Manual FSGETPATH(2)

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

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


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

The () 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.

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.

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.

The fsgetpath() function will fail if:

[]
Read permissions are denied on any component of the pathname.
[]
The underlying filesystem does not support this call.
[]
buflen is larger than 8192
[]
An I/O error occurred while reading from the file system.
[]
The calling process does not have appropriate privileges.
[]
The Filesystem object does not exist.
[]
restrict_buf points to memory not valid in the callers address space.
[]
restrict_buf is not large enough to hold the path.

getattrlist(2) statfs(2) stat(2)

The fsgetpath() function call appeared in macOS version 10.13

July 27, 2017 Darwin