bsd/man/man2/fsgetpath.2

   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
  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.
  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 .