--- /dev/null
+.\" 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
+.
projects / apple / xnu.git / blobdiff