lib/libc/sys/pathconf.2

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)pathconf.2  8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd July 7, 2009
  32 .Dt PATHCONF 2
  33 .Os
  34 .Sh NAME
  35 .Nm pathconf ,
  36 .Nm lpathconf ,
  37 .Nm fpathconf
  38 .Nd get configurable pathname variables
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft long
  44 .Fn pathconf "const char *path" "int name"
  45 .Ft long
  46 .Fn lpathconf "const char *path" "int name"
  47 .Ft long
  48 .Fn fpathconf "int fd" "int name"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn pathconf ,
  52 .Fn lpathconf
  53 and
  54 .Fn fpathconf
  55 system calls provide a method for applications to determine the current
  56 value of a configurable system limit or option variable associated
  57 with a pathname or file descriptor.
  58 .Pp
  59 For
  60 .Fn pathconf
  61 and
  62 .Fn lpathconf ,
  63 the
  64 .Fa path
  65 argument is the name of a file or directory.
  66 For
  67 .Fn fpathconf ,
  68 the
  69 .Fa fd
  70 argument is an open file descriptor.
  71 The
  72 .Fa name
  73 argument specifies the system variable to be queried.
  74 Symbolic constants for each name value are found in the include file
  75 .Li <unistd.h> .
  76 .Pp
  77 The
  78 .Fn lpathconf
  79 system call is like
  80 .Fn pathconf
  81 except in the case where the named file is a symbolic link,
  82 in which case
  83 .Fn lpathconf
  84 returns information about the link,
  85 while
  86 .Fn pathconf
  87 returns information about the file the link references.
  88 .Pp
  89 The available values are as follows:
  90 .Pp
  91 .Bl -tag -width 6n
  92 .Pp
  93 .It Li _PC_LINK_MAX
  94 The maximum file link count.
  95 .It Li _PC_MAX_CANON
  96 The maximum number of bytes in terminal canonical input line.
  97 .It Li _PC_MAX_INPUT
  98 The minimum maximum number of bytes for which space is available in
  99 a terminal input queue.
 100 .It Li _PC_NAME_MAX
 101 The maximum number of bytes in a file name.
 102 .It Li _PC_PATH_MAX
 103 The maximum number of bytes in a pathname.
 104 .It Li _PC_PIPE_BUF
 105 The maximum number of bytes which will be written atomically to a pipe.
 106 .It Li _PC_CHOWN_RESTRICTED
 107 Return 1 if appropriate privilege is required for the
 108 .Xr chown 2
 109 system call, otherwise 0.
 110 .St -p1003.1-2001
 111 requires appropriate privilege in all cases, but this behavior was optional
 112 in prior editions of the standard.
 113 .It Li _PC_NO_TRUNC
 114 Return greater than zero if attempts to use pathname components longer than
 115 .Brq Dv NAME_MAX
 116 will result in an
 117 .Bq Er ENAMETOOLONG
 118 error; otherwise, such components will be truncated to
 119 .Brq Dv NAME_MAX .
 120 .St -p1003.1-2001
 121 requires the error in all cases, but this behavior was optional in prior
 122 editions of the standard, and some
 123 .No non- Ns Tn POSIX Ns -compliant
 124 file systems do not support this behavior.
 125 .It Li _PC_VDISABLE
 126 Returns the terminal character disabling value.
 127 .It Li _PC_ASYNC_IO
 128 Return 1 if asynchronous I/O is supported, otherwise 0.
 129 .It Li _PC_PRIO_IO
 130 Returns 1 if prioritised I/O is supported for this file,
 131 otherwise 0.
 132 .It Li _PC_SYNC_IO
 133 Returns 1 if synchronised I/O is supported for this file, otherwise 0.
 134 .It Li _PC_ALLOC_SIZE_MIN
 135 Minimum number of bytes of storage allocated for any portion of a file.
 136 .It Li _PC_FILESIZEBITS
 137 Number of bits needed to represent the maximum file size.
 138 .It Li _PC_REC_INCR_XFER_SIZE
 139 Recommended increment for file transfer sizes between
 140 .Dv _PC_REC_MIN_XFER_SIZE
 141 and
 142 .Dv _PC_REC_MAX_XFER_SIZE .
 143 .It Li _PC_REC_MAX_XFER_SIZE
 144 Maximum recommended file transfer size.
 145 .It Li _PC_REC_MIN_XFER_SIZE
 146 Minimum recommended file transfer size.
 147 .It Li _PC_REC_XFER_ALIGN
 148 Recommended file transfer buffer alignment.
 149 .It Li _PC_SYMLINK_MAX
 150 Maximum number of bytes in a symbolic link.
 151 .It Li _PC_ACL_EXTENDED
 152 Returns 1 if an Access Control List (ACL) can be set on the specified
 153 file, otherwise 0.
 154 .It Li _PC_ACL_NFS4
 155 Returns 1 if an NFSv4 ACLs can be set on the specified
 156 file, otherwise 0.
 157 .It Li _PC_ACL_PATH_MAX
 158 Maximum number of ACL entries per file.
 159 .It Li _PC_CAP_PRESENT
 160 Returns 1 if a capability state can be set on the specified file,
 161 otherwise 0.
 162 .It Li _PC_INF_PRESENT
 163 Returns 1 if an information label can be set on the specified file,
 164 otherwise 0.
 165 .It Li _PC_MAC_PRESENT
 166 Returns 1 if a Mandatory Access Control (MAC) label can be set on the
 167 specified file, otherwise 0.
 168 .It Li _PC_MIN_HOLE_SIZE
 169 If a file system supports the reporting of holes (see
 170 .Xr lseek 2 ,
 171 .Fn pathconf
 172 and
 173 .Fn fpathconf
 174 return a positive number that represents the minimum hole size returned in
 175 bytes.
 176 The offsets of holes returned will be aligned to this same value.
 177 A special value of 1 is returned if the file system does not specify the minimum
 178 hole size but still reports holes.
 179 .El
 180 .Sh RETURN VALUES
 181 If the call to
 182 .Fn pathconf
 183 or
 184 .Fn fpathconf
 185 is not successful, \-1 is returned and
 186 .Va errno
 187 is set appropriately.
 188 Otherwise, if the variable is associated with functionality that does
 189 not have a limit in the system, \-1 is returned and
 190 .Va errno
 191 is not modified.
 192 Otherwise, the current variable value is returned.
 193 .Sh ERRORS
 194 If any of the following conditions occur, the
 195 .Fn pathconf
 196 and
 197 .Fn fpathconf
 198 system calls shall return -1 and set
 199 .Va errno
 200 to the corresponding value.
 201 .Bl -tag -width Er
 202 .It Bq Er EINVAL
 203 The value of the
 204 .Fa name
 205 argument is invalid.
 206 .It Bq Er EINVAL
 207 The implementation does not support an association of the variable
 208 name with the associated file.
 209 .El
 210 .Pp
 211 The
 212 .Fn pathconf
 213 system call
 214 will fail if:
 215 .Bl -tag -width Er
 216 .It Bq Er ENOTDIR
 217 A component of the path prefix is not a directory.
 218 .It Bq Er ENAMETOOLONG
 219 A component of a pathname exceeded
 220 .Brq Dv NAME_MAX
 221 characters (but see
 222 .Dv _PC_NO_TRUNC
 223 above),
 224 or an entire path name exceeded
 225 .Brq Dv PATH_MAX
 226 characters.
 227 .It Bq Er ENOENT
 228 The named file does not exist.
 229 .It Bq Er EACCES
 230 Search permission is denied for a component of the path prefix.
 231 .It Bq Er ELOOP
 232 Too many symbolic links were encountered in translating the pathname.
 233 .It Bq Er EIO
 234 An I/O error occurred while reading from or writing to the file system.
 235 .El
 236 .Pp
 237 .Bl -tag -width Er
 238 The
 239 .Fn fpathconf
 240 system call
 241 will fail if:
 242 .It Bq Er EBADF
 243 The
 244 .Fa fd
 245 argument
 246 is not a valid open file descriptor.
 247 .It Bq Er EIO
 248 An I/O error occurred while reading from or writing to the file system.
 249 .El
 250 .Sh SEE ALSO
 251 .Xr lseek 2 ,
 252 .Xr sysctl 3
 253 .Sh HISTORY
 254 The
 255 .Fn pathconf
 256 and
 257 .Fn fpathconf
 258 system calls first appeared in
 259 .Bx 4.4 .
 260 The
 261 .Fn lpathconf
 262 system call first appeared in
 263 .Fx 8.0 .