lib/libc/sys/pathconf.2

   1 .\"     $NetBSD: pathconf.2,v 1.27 2010/07/26 12:30:16 njoly 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 July 26, 2010
  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
  70 .In unistd.h
  71 header.
  72 .Pp
  73 The available values are as follows:
  74 .Pp
  75 .Bl -tag -width "123456"
  76 .It Li _PC_LINK_MAX
  77 The maximum file link count.
  78 .It Li _PC_MAX_CANON
  79 The maximum number of bytes in terminal canonical input line.
  80 .It Li _PC_MAX_INPUT
  81 The minimum maximum number of bytes for which space is available in
  82 a terminal input queue.
  83 .It Li _PC_NAME_MAX
  84 The maximum number of bytes in a filename,
  85 not including a terminating null character.
  86 .It Li _PC_PATH_MAX
  87 The maximum number of bytes in a pathname,
  88 including the terminating null character.
  89 .It Li _PC_PIPE_BUF
  90 The maximum number of bytes which will be written atomically to a pipe.
  91 .It Li _PC_CHOWN_RESTRICTED
  92 Return 1 if appropriate privileges are required for the
  93 .Xr chown 2
  94 system call, otherwise 0.
  95 .It Li _PC_NO_TRUNC
  96 Return 0 if filenames longer than
  97 .Brq Dv NAME_MAX
  98 are silently truncated, or non-zero if an error is generated when
  99 .Brq Dv NAME_MAX
 100 is exceeded.
 101 .It Li _PC_VDISABLE
 102 Returns the terminal character disabling value.
 103 .It Li _PC_SYNC_IO
 104 Returns 1 if synchronized I/O is supported, otherwise 0.
 105 .It Li _PC_FILESIZEBITS
 106 If the maximum size file that could ever exist on the mounted file system is
 107 .Dv maxsize ,
 108 then the returned value is 2 plus the floor of the base 2 logarithm of
 109 .Dv maxsize .
 110 .It Li _PC_SYMLINK_MAX
 111 The maximum number of bytes in a symbolic link.
 112 .It Li _PC_2_SYMLINKS
 113 When referring to a directory the system supports the creation of symbolic
 114 links within that directory; for nondirectory files, the meaning of
 115 .Dv {_PC_2_SYMLINKS}
 116 is undefined.
 117 .El
 118 .Sh RETURN VALUES
 119 If the call to
 120 .Nm pathconf
 121 or
 122 .Nm fpathconf
 123 is not successful, \-1 is returned and
 124 .Va errno
 125 is set appropriately.
 126 Otherwise, if the variable is associated with functionality that does
 127 not have a limit in the system, \-1 is returned and
 128 .Va errno
 129 is not modified.
 130 Otherwise, the current variable value is returned.
 131 .Sh ERRORS
 132 If any of the following conditions occur, the
 133 .Nm pathconf
 134 and
 135 .Nm fpathconf
 136 functions shall return \-1 and set
 137 .Va errno
 138 to the corresponding value.
 139 .Bl -tag -width Er
 140 .It Bq Er EINVAL
 141 The value of the
 142 .Fa name
 143 argument is invalid, or
 144 the implementation does not support an association of the variable
 145 name with the associated file.
 146 .El
 147 .Pp
 148 .Fn pathconf
 149 will fail if:
 150 .Bl -tag -width ENAMETOOLONGAA
 151 .It Bq Er EACCES
 152 Search permission is denied for a component of the path prefix.
 153 .It Bq Er EIO
 154 An I/O error occurred while reading from or writing to the file system.
 155 .It Bq Er ELOOP
 156 Too many symbolic links were encountered in translating the pathname.
 157 .It Bq Er ENAMETOOLONG
 158 A component of a pathname exceeded 255 characters,
 159 or an entire path name exceeded 1023 characters.
 160 .It Bq Er ENOENT
 161 The named file does not exist.
 162 .It Bq Er ENOTDIR
 163 A component of the path prefix is not a directory.
 164 .El
 165 .Pp
 166 .Fn fpathconf
 167 will fail if:
 168 .Bl -tag -width [EFAULT]
 169 .It Bq Er EBADF
 170 .Fa fd
 171 is not a valid open file descriptor.
 172 .It Bq Er EIO
 173 An I/O error occurred while reading from or writing to the file system.
 174 .El
 175 .Sh SEE ALSO
 176 .Xr sysctl 3
 177 .Sh STANDARDS
 178 The
 179 .Fn pathconf
 180 and
 181 .Fn fpathconf
 182 functions conform to
 183 .St -p1003.1-90 .
 184 .Sh HISTORY
 185 The
 186 .Nm pathconf
 187 and
 188 .Nm fpathconf
 189 functions first appeared in
 190 .Bx 4.4 .