1.\" Copyright (c) 2017 Apple Computer, Inc. All rights reserved. 2.\" 3.\" The contents of this file constitute Original Code as defined in and 4.\" are subject to the Apple Public Source License Version 1.1 (the 5.\" "License"). You may not use this file except in compliance with the 6.\" License. Please obtain a copy of the License at 7.\" http://www.apple.com/publicsource and read it before using this file. 8.\" 9.\" This Original Code and all software distributed under the License are 10.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 11.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 12.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 13.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 14.\" License for the specific language governing rights and limitations 15.\" under the License. 16.\" 17.\" @(#)fsgetpath.2 18. 19.Dd July 27, 2017 20.Dt FSGETPATH 2 21.Os Darwin 22.Sh NAME 23.Nm fsgetpath 24.Nd get the path associated with filesystem node identifier (inode number/link id/object id) 25.Sh SYNOPSIS 26.Fd #include <sys/attr.h> 27.Fd #include <sys/fsgetpath.h> 28.Pp 29.Ft ssize_t 30.Fn fsgetpath "char * restrict_buf" "size_t buflen" "fsid_t * fsid" "uint64_t obj_id" 31. 32.Sh DESCRIPTION 33The 34.Fn fsgetpath 35function returns the path in a caller provided buffer 36.Fa restrict_buf 37of length indicated by 38.Fa buflen 39associated with a filesystem object identified by 40.Fa fsid 41and 42.Fa obj_id. 43.Fa fsid 44is a pointer to a structure which identifies a filesystem to which the object belongs. 45It is obtained by the value returned for ATTR_CMN_FSID in a previous call to 46.Xr getattrlist 2 47or the 48.Fa f_fsid 49field of the 50.Vt statfs 51structure returned by 52.Xr statfs 2 . 53.Fa obj_id 54can be any one of of a object identifier i.e. ATTR_CMN_FILEID returned by 55.Xr getattrlist 2 56or 57.Fa st_ino 58field of the 59.Vt stat 60structure returned by 61.Xr stat 2 62or a link id returned in ATTR_CMNEXT_LINKID by a previous call to 63.Xr getattrlist 2 . 64Using a linkid will result in a more accurate path in case the filesystem object is a 65hard link. If a inode number is passed and the object is a hard link, any one of the 66multiple paths to that filesystem object may be returned. 67.Sh RETURN VALUES 68Upon successful completion, 69.Fn fsgetpath 70returns the length of the path including the null terminator. Otherwise, a value of -1 is returned and errno is set to indicate the error. 71.Pp 72.Sh COMPATIBILITY 73Not all volumes support 74.Fn fsgetpath . 75A volume can be tested for 76.Fn fsgetpath 77support by using 78.Xr getattrlist 2 79to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_FMT_PATH_FROM_ID flag. 80.Pp 81.Sh ERRORS 82The 83.Fn fsgetpath 84function will fail if: 85.Bl -tag -width Er 86. 87.It Bq Er EACCES 88Read permissions are denied on any component of the pathname. 89. 90.It Bq Er ENOTSUP 91The underlying filesystem does not support this call. 92. 93.It Bq Er EINVAL 94.Fa buflen 95is larger than 8192 96. 97.It Bq Er EIO 98An I/O error occurred while reading from the file system. 99. 100.It Bq Er EPERM 101The calling process does not have appropriate privileges. 102. 103.It Bq Er ENOENT 104The Filesystem object does not exist. 105. 106.It Bq Er EFAULT 107restrict_buf points to memory not valid in the callers address space. 108. 109.It Bq Er ENOSPC 110restrict_buf is not large enough to hold the path. 111. 112.El 113. 114.Pp 115. 116.Sh SEE ALSO 117. 118.Xr getattrlist 2 119.Xr statfs 2 120.Xr stat 2 121. 122.Sh HISTORY 123The 124.Fn fsgetpath 125function call appeared in macOS version 10.13 126. 127