lib/libc/sys/pathconf.2

   1 .\"     $NetBSD: pathconf.2,v 1.28 2014/06/09 09:15:48 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 .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 0 if filenames longer than
  96 .Brq Dv NAME_MAX
  97 are silently truncated, or non-zero if an error is generated when
  98 .Brq Dv NAME_MAX
  99 is exceeded.
 100 .It Li _PC_VDISABLE
 101 Returns the terminal character disabling value.
 102 .It Li _PC_SYNC_IO
 103 Returns 1 if synchronized I/O is supported, otherwise 0.
 104 .It Li _PC_FILESIZEBITS
 105 If the maximum size file that could ever exist on the mounted file system is
 106 .Dv maxsize ,
 107 then the returned value is 2 plus the floor of the base 2 logarithm of
 108 .Dv maxsize .
 109 .It Li _PC_SYMLINK_MAX
 110 The maximum number of bytes in a symbolic link.
 111 .It Li _PC_2_SYMLINKS
 112 When referring to a directory the system supports the creation of symbolic
 113 links within that directory; for nondirectory files, the meaning of
 114 .Dv {_PC_2_SYMLINKS}
 115 is undefined.
 116 .El
 117 .Sh RETURN VALUES
 118 If the call to
 119 .Nm pathconf
 120 or
 121 .Nm fpathconf
 122 is not successful, \-1 is returned and
 123 .Va errno
 124 is set appropriately.
 125 Otherwise, if the variable is associated with functionality that does
 126 not have a limit in the system, \-1 is returned and
 127 .Va errno
 128 is not modified.
 129 Otherwise, the current variable value is returned.
 130 .Sh ERRORS
 131 If any of the following conditions occur, the
 132 .Nm pathconf
 133 and
 134 .Nm fpathconf
 135 functions shall return \-1 and set
 136 .Va errno
 137 to the corresponding value.
 138 .Bl -tag -width Er
 139 .It Bq Er EINVAL
 140 The value of the
 141 .Fa name
 142 argument is invalid, or
 143 the implementation does not support an association of the variable
 144 name with the associated file.
 145 .El
 146 .Pp
 147 .Fn pathconf
 148 will fail if:
 149 .Bl -tag -width ENAMETOOLONGAA
 150 .It Bq Er EACCES
 151 Search permission is denied for a component of the path prefix.
 152 .It Bq Er EIO
 153 An I/O error occurred while reading from or writing to the file system.
 154 .It Bq Er ELOOP
 155 Too many symbolic links were encountered in translating the pathname.
 156 .It Bq Er ENAMETOOLONG
 157 A component of a pathname exceeded
 158 .Brq Dv NAME_MAX
 159 characters, or an entire path name exceeded
 160 .Brq Dv PATH_MAX
 161 characters.
 162 .It Bq Er ENOENT
 163 The named file does not exist.
 164 .It Bq Er ENOTDIR
 165 A component of the path prefix is not a directory.
 166 .El
 167 .Pp
 168 .Fn fpathconf
 169 will fail if:
 170 .Bl -tag -width [EFAULT]
 171 .It Bq Er EBADF
 172 .Fa fd
 173 is not a valid open file descriptor.
 174 .It Bq Er EIO
 175 An I/O error occurred while reading from or writing to the file system.
 176 .El
 177 .Sh SEE ALSO
 178 .Xr sysctl 3
 179 .Sh STANDARDS
 180 The
 181 .Fn pathconf
 182 and
 183 .Fn fpathconf
 184 functions conform to
 185 .St -p1003.1-90 .
 186 .Sh HISTORY
 187 The
 188 .Nm pathconf
 189 and
 190 .Nm fpathconf
 191 functions first appeared in
 192 .Bx 4.4 .