.\" Copyright (c) 2017 Apple Computer, Inc. All rights reserved. .\" .\" The contents of this file constitute Original Code as defined in and .\" are subject to the Apple Public Source License Version 1.1 (the .\" "License"). You may not use this file except in compliance with the .\" License. Please obtain a copy of the License at .\" http://www.apple.com/publicsource and read it before using this file. .\" .\" This Original Code and all software distributed under the License are .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the .\" License for the specific language governing rights and limitations .\" under the License. .\" .\" @(#)fsgetpath.2 . .Dd July 27, 2017 .Dt FSGETPATH 2 .Os Darwin .Sh NAME .Nm fsgetpath .Nd get the path associated with filesystem node identifier (inode number/link id/object id) .Sh SYNOPSIS .Fd #include <sys/attr.h> .Fd #include <sys/fsgetpath.h> .Pp .Ft ssize_t .Fn fsgetpath "char * restrict_buf" "size_t buflen" "fsid_t * fsid" "uint64_t obj_id" . .Sh DESCRIPTION The .Fn fsgetpath function returns the path in a caller provided buffer .Fa restrict_buf of length indicated by .Fa buflen associated with a filesystem object identified by .Fa fsid and .Fa obj_id. .Fa 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 .Xr getattrlist 2 or the .Fa f_fsid field of the .Vt statfs structure returned by .Xr statfs 2 . .Fa obj_id can be any one of of a object identifier i.e. ATTR_CMN_FILEID returned by .Xr getattrlist 2 or .Fa st_ino field of the .Vt stat structure returned by .Xr stat 2 or a link id returned in ATTR_CMNEXT_LINKID by a previous call to .Xr 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. .Sh RETURN VALUES Upon successful completion, .Fn fsgetpath returns the path length. Otherwise, a value of -1 is returned and errno is set to indicate the error. .Pp .Sh COMPATIBILITY Not all volumes support .Fn fsgetpath . A volume can be tested for .Fn fsgetpath support by using .Xr getattrlist 2 to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_FMT_PATH_FROM_ID flag. .Pp .Sh ERRORS The .Fn fsgetpath function will fail if: .Bl -tag -width Er . .It Bq Er EACCES Read permissions are denied on any component of the pathname. . .It Bq Er ENOTSUP The underlying filesystem does not support this call. . .It Bq Er EINVAL .Fa buflen is larger than PAGE_SIZE . .It Bq Er EIO An I/O error occurred while reading from the file system. . .It Bq Er EPERM The calling process does not have appropriate privileges. . .It Bq Er ENOENT The Filesystem object does not exist. . .It Bq Er EFAULT restrict_buf points to memory not valid in the callers address space. . .It Bq Er ENOSPC restrict_buf is not large enough to hold the path. . .El . .Pp . .Sh SEE ALSO . .Xr getattrlist 2 .Xr statfs 2 .Xr stat 2 . .Sh HISTORY The .Fn fsgetpath function call appeared in macOS version 10.13 .