127 lines
3.4 KiB
Groff
127 lines
3.4 KiB
Groff
|
.\" 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 length of the path including the null terminator. 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
|
||
|
|
.
|