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 .\" 3. 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: src/lib/libc/sys/pathconf.2,v 1.4.2.6 2001/12/14 18:34:01 ru Exp $
  30 .\"
  31 .Dd April 13, 2013
  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 functions 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 .In 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 .Bl -tag -width 6n
  91 .It Li _PC_LINK_MAX
  92 The maximum file link count.
  93 .It Li _PC_MAX_CANON
  94 The maximum number of bytes in terminal canonical input line.
  95 .It Li _PC_MAX_INPUT
  96 The minimum maximum number of bytes for which space is available in
  97 a terminal input queue.
  98 .It Li _PC_NAME_MAX
  99 The maximum number of bytes in a file name.
 100 .It Li _PC_PATH_MAX
 101 The maximum number of bytes in a pathname.
 102 .It Li _PC_PIPE_BUF
 103 The maximum number of bytes which will be written atomically to a pipe.
 104 .It Li _PC_CHOWN_RESTRICTED
 105 Return 1 if appropriate privileges are required for the
 106 .Xr chown 2
 107 system call, otherwise 0.
 108 .It Li _PC_NO_TRUNC
 109 Return 1 if file names longer than KERN_NAME_MAX are truncated.
 110 .It Li _PC_VDISABLE
 111 Returns the terminal character disabling value.
 112 .El
 113 .Sh RETURN VALUES
 114 If the call to
 115 .Fn pathconf
 116 or
 117 .Fn fpathconf
 118 is not successful, \-1 is returned and
 119 .Va errno
 120 is set appropriately.
 121 Otherwise, if the variable is associated with functionality that does
 122 not have a limit in the system, \-1 is returned and
 123 .Va errno
 124 is not modified.
 125 Otherwise, the current variable value is returned.
 126 .Sh ERRORS
 127 If any of the following conditions occur, the
 128 .Fn pathconf ,
 129 .Fn lpathconf
 130 and
 131 .Fn fpathconf
 132 functions shall return -1 and set
 133 .Va errno
 134 to the corresponding value.
 135 .Bl -tag -width Er
 136 .It Bq Er EINVAL
 137 The value of the
 138 .Fa name
 139 argument is invalid.
 140 .It Bq Er EINVAL
 141 The implementation does not support an association of the variable
 142 name with the associated file.
 143 .El
 144 .Pp
 145 .Fn Pathconf
 146 and
 147 .Fn lpathconf
 148 will fail if:
 149 .Bl -tag -width Er
 150 .It Bq Er ENOTDIR
 151 A component of the path prefix is not a directory.
 152 .It Bq Er ENAMETOOLONG
 153 A component of a pathname exceeded 255 characters,
 154 or an entire path name exceeded 1023 characters.
 155 .It Bq Er ENOENT
 156 The named file does not exist.
 157 .It Bq Er EACCES
 158 Search permission is denied for a component of the path prefix.
 159 .It Bq Er ELOOP
 160 Too many symbolic links were encountered in translating the pathname.
 161 .It Bq Er EIO
 162 An I/O error occurred while reading from or writing to the file system.
 163 .El
 164 .Pp
 165 .Fn Fpathconf
 166 will fail if:
 167 .Bl -tag -width Er
 168 .It Bq Er EBADF
 169 .Fa fd
 170 is not a valid open file descriptor.
 171 .It Bq Er EIO
 172 An I/O error occurred while reading from or writing to the file system.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr sysctl 3
 176 .Sh HISTORY
 177 The
 178 .Fn pathconf
 179 and
 180 .Fn fpathconf
 181 functions first appeared in
 182 .Bx 4.4 .
 183 The
 184 .Fn lpathconf
 185 system call first appeared in
 186 .Dx 3.5 .