[apple/xnu.git] / bsd / man / man2 / fsgetpath.2

.\" 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
.
Commit	Line	Data
5ba3f43e A	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
	33	The
	34	.Fn fsgetpath
	35	function returns the path in a caller provided buffer
	36	.Fa restrict_buf
	37	of length indicated by
	38	.Fa buflen
	39	associated with a filesystem object identified by
	40	.Fa fsid
	41	and
	42	.Fa obj_id.
	43	.Fa fsid
	44	is a pointer to a structure which identifies a filesystem to which the object belongs.
	45	It is obtained by the value returned for ATTR_CMN_FSID in a previous call to
	46	.Xr getattrlist 2
	47	or the
	48	.Fa f_fsid
	49	field of the
	50	.Vt statfs
	51	structure returned by
	52	.Xr statfs 2 .
	53	.Fa obj_id
	54	can be any one of of a object identifier i.e. ATTR_CMN_FILEID returned by
	55	.Xr getattrlist 2
	56	or
	57	.Fa st_ino
	58	field of the
	59	.Vt stat
	60	structure returned by
	61	.Xr stat 2
	62	or a link id returned in ATTR_CMNEXT_LINKID by a previous call to
	63	.Xr getattrlist 2 .
	64	Using a linkid will result in a more accurate path in case the filesystem object is a
65	hard link. If a inode number is passed and the object is a hard link, any one of the
66	multiple paths to that filesystem object may be returned.
67	.Sh RETURN VALUES
68	Upon successful completion,
69	.Fn fsgetpath
cb323159	70	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.
5ba3f43e A	71	.Pp
	72	.Sh COMPATIBILITY
	73	Not all volumes support
	74	.Fn fsgetpath .
	75	A volume can be tested for
	76	.Fn fsgetpath
	77	support by using
	78	.Xr getattrlist 2
	79	to get the volume capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the VOL_CAP_FMT_PATH_FROM_ID flag.
	80	.Pp
	81	.Sh ERRORS
	82	The
	83	.Fn fsgetpath
	84	function will fail if:
	85	.Bl -tag -width Er
	86	.
	87	.It Bq Er EACCES
	88	Read permissions are denied on any component of the pathname.
	89	.
	90	.It Bq Er ENOTSUP
	91	The underlying filesystem does not support this call.
	92	.
	93	.It Bq Er EINVAL
	94	.Fa buflen
	95	is larger than PAGE_SIZE
	96	.
	97	.It Bq Er EIO
	98	An I/O error occurred while reading from the file system.
	99	.
	100	.It Bq Er EPERM
	101	The calling process does not have appropriate privileges.
	102	.
	103	.It Bq Er ENOENT
	104	The Filesystem object does not exist.
	105	.
	106	.It Bq Er EFAULT
	107	restrict_buf points to memory not valid in the callers address space.
	108	.
	109	.It Bq Er ENOSPC
	110	restrict_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
	123	The
	124	.Fn fsgetpath
	125	function call appeared in macOS version 10.13
	126	.