lib/libc/sys/pathconf.2

   1 .\"     $NetBSD: pathconf.2,v 1.21 2008/08/14 18:00:08 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)pathconf.2  8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd August 14, 2008
  33 .Dt PATHCONF 2
  34 .Os
  35 .Sh NAME
  36 .Nm pathconf ,
  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 fpathconf "int fd" "int name"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn pathconf
  50 and
  51 .Fn fpathconf
  52 functions provide a method for applications to determine the current
  53 value of a configurable system limit or option variable associated
  54 with a pathname or file descriptor.
  55 .Pp
  56 For
  57 .Nm pathconf ,
  58 the
  59 .Fa path
  60 argument is the name of a file or directory.
  61 For
  62 .Nm fpathconf ,
  63 the
  64 .Fa fd
  65 argument is an open file descriptor.
  66 The
  67 .Fa name
  68 argument specifies the system variable to be queried.
  69 Symbolic constants for each name value are found in the include file
  70 .Li \*[Lt]unistd.h\*[Gt] .
  71 .Pp
  72 The available values are as follows:
  73 .Pp
  74 .Bl -tag -width "123456"
  75 .It Li _PC_LINK_MAX
  76 The maximum file link count.
  77 .It Li _PC_MAX_CANON
  78 The maximum number of bytes in terminal canonical input line.
  79 .It Li _PC_MAX_INPUT
  80 The minimum maximum number of bytes for which space is available in
  81 a terminal input queue.
  82 .It Li _PC_NAME_MAX
  83 The maximum number of bytes in a filename,
  84 not including a terminating null character.
  85 .It Li _PC_PATH_MAX
  86 The maximum number of bytes in a pathname,
  87 including the terminating null character.
  88 .It Li _PC_PIPE_BUF
  89 The maximum number of bytes which will be written atomically to a pipe.
  90 .It Li _PC_CHOWN_RESTRICTED
  91 Return 1 if appropriate privileges are required for the
  92 .Xr chown 2
  93 system call, otherwise 0.
  94 .It Li _PC_NO_TRUNC
  95 Return 1 if filenames longer than
  96 .Dv {NAME_MAX}
  97 are truncated.
  98 .It Li _PC_VDISABLE
  99 Returns the terminal character disabling value.
 100 .It Li _PC_SYNC_IO
 101 Returns 1 if synchronized I/O is supported, otherwise 0.
 102 .It Li _PC_FILESIZEBITS
 103 If the maximum size file that could ever exist on the mounted file system is
 104 .Dv maxsize ,
 105 then the returned value is 2 plus the floor of the base 2 logarithm of
 106 .Dv maxsize .
 107 .It Li _PC_SYMLINK_MAX
 108 The maximum number of bytes in a symbolic link.
 109 .It Li _PC_2_SYMLINKS
 110 When referring to a directory the system supports the creation of symbolic
 111 links within that directory; for nondirectory files, the meaning of
 112 .Dv {_PC_2_SYMLINKS}
 113 is undefined.
 114 .El
 115 .Sh RETURN VALUES
 116 If the call to
 117 .Nm pathconf
 118 or
 119 .Nm fpathconf
 120 is not successful, \-1 is returned and
 121 .Va errno
 122 is set appropriately.
 123 Otherwise, if the variable is associated with functionality that does
 124 not have a limit in the system, \-1 is returned and
 125 .Va errno
 126 is not modified.
 127 Otherwise, the current variable value is returned.
 128 .Sh ERRORS
 129 If any of the following conditions occur, the
 130 .Nm pathconf
 131 and
 132 .Nm fpathconf
 133 functions shall return \-1 and set
 134 .Va errno
 135 to the corresponding value.
 136 .Bl -tag -width Er
 137 .It Bq Er EINVAL
 138 The value of the
 139 .Fa name
 140 argument is invalid, or
 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 will fail if:
 147 .Bl -tag -width ENAMETOOLONGAA
 148 .It Bq Er EACCES
 149 Search permission is denied for a component of the path prefix.
 150 .It Bq Er EIO
 151 An I/O error occurred while reading from or writing to the file system.
 152 .It Bq Er ELOOP
 153 Too many symbolic links were encountered in translating the pathname.
 154 .It Bq Er ENAMETOOLONG
 155 A component of a pathname exceeded 255 characters,
 156 or an entire path name exceeded 1023 characters.
 157 .It Bq Er ENOENT
 158 The named file does not exist.
 159 .It Bq Er ENOTDIR
 160 A component of the path prefix is not a directory.
 161 .El
 162 .Pp
 163 .Fn fpathconf
 164 will fail if:
 165 .Bl -tag -width [EFAULT]
 166 .It Bq Er EBADF
 167 .Fa fd
 168 is not a valid open file descriptor.
 169 .It Bq Er EIO
 170 An I/O error occurred while reading from or writing to the file system.
 171 .El
 172 .Sh SEE ALSO
 173 .Xr sysctl 3
 174 .Sh STANDARDS
 175 The
 176 .Fn pathconf
 177 and
 178 .Fn fpathconf
 179 functions conform to
 180 .St -p1003.1-90 .
 181 .Sh HISTORY
 182 The
 183 .Nm pathconf
 184 and
 185 .Nm fpathconf
 186 functions first appeared in
 187 .Bx 4.4 .