man3/fpathconf.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Wed Jul 28 11:12:26 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\"
   8 .\" FIXME Probably all of the following should be documented:
   9 .\"     _PC_SYNC_IO,
  10 .\"     _PC_ASYNC_IO,
  11 .\"     _PC_PRIO_IO,
  12 .\"     _PC_SOCK_MAXBUF,
  13 .\"     _PC_FILESIZEBITS,
  14 .\"     _PC_REC_INCR_XFER_SIZE,
  15 .\"     _PC_REC_MAX_XFER_SIZE,
  16 .\"     _PC_REC_MIN_XFER_SIZE,
  17 .\"     _PC_REC_XFER_ALIGN,
  18 .\"     _PC_ALLOC_SIZE_MIN,
  19 .\"     _PC_SYMLINK_MAX,
  20 .\"     _PC_2_SYMLINKS
  21 .\"
  22 .TH FPATHCONF 3  2021-03-22 "Linux man-pages (unreleased)"
  23 .SH NAME
  24 fpathconf, pathconf \- get configuration values for files
  25 .SH LIBRARY
  26 Standard C library
  27 .RI ( libc ", " \-lc )
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <unistd.h>
  31 .PP
  32 .BI "long fpathconf(int " fd ", int " name );
  33 .BI "long pathconf(const char *" path ", int " name );
  34 .fi
  35 .SH DESCRIPTION
  36 .BR fpathconf ()
  37 gets a value for the configuration option
  38 .I name
  39 for the open file descriptor
  40 .IR fd .
  41 .PP
  42 .BR pathconf ()
  43 gets a value for configuration option
  44 .I name
  45 for the filename
  46 .IR path .
  47 .PP
  48 The corresponding macros defined in
  49 .I <unistd.h>
  50 are minimum values; if an application wants to take advantage of values
  51 which may change, a call to
  52 .BR fpathconf ()
  53 or
  54 .BR pathconf ()
  55 can be made, which may yield more liberal results.
  56 .PP
  57 Setting
  58 .I name
  59 equal to one of the following constants returns the following
  60 configuration options:
  61 .TP
  62 .B _PC_LINK_MAX
  63 The maximum number of links to the file.
  64 If
  65 .I fd
  66 or
  67 .I path
  68 refer to a directory, then the value applies to the whole directory.
  69 The corresponding macro is
  70 .BR _POSIX_LINK_MAX .
  71 .TP
  72 .B _PC_MAX_CANON
  73 The maximum length of a formatted input line, where
  74 .I fd
  75 or
  76 .I path
  77 must refer to a terminal.
  78 The corresponding macro is
  79 .BR _POSIX_MAX_CANON .
  80 .TP
  81 .B _PC_MAX_INPUT
  82 The maximum length of an input line, where
  83 .I fd
  84 or
  85 .I path
  86 must refer to a terminal.
  87 The corresponding macro is
  88 .BR _POSIX_MAX_INPUT .
  89 .TP
  90 .B _PC_NAME_MAX
  91 The maximum length of a filename in the directory
  92 .I path
  93 or
  94 .I fd
  95 that the process is allowed to create.
  96 The corresponding macro is
  97 .BR _POSIX_NAME_MAX .
  98 .TP
  99 .B _PC_PATH_MAX
 100 The maximum length of a relative pathname when
 101 .I path
 102 or
 103 .I fd
 104 is the current working directory.
 105 The corresponding macro is
 106 .BR _POSIX_PATH_MAX .
 107 .TP
 108 .B _PC_PIPE_BUF
 109 The maximum number of bytes that can be written atomically to a pipe of FIFO.
 110 For
 111 .BR fpathconf (),
 112 .I fd
 113 should refer to a pipe or FIFO.
 114 For
 115 .BR fpathconf (),
 116 .I path
 117 should refer to a FIFO or a directory; in the latter case,
 118 the returned value corresponds to FIFOs created in that directory.
 119 The corresponding macro is
 120 .BR _POSIX_PIPE_BUF .
 121 .TP
 122 .B _PC_CHOWN_RESTRICTED
 123 This returns a positive value if the use of
 124 .BR chown (2)
 125 and
 126 .BR fchown (2)
 127 for changing a file's user ID is restricted to a process
 128 with appropriate privileges,
 129 and changing a file's group ID to a value other than the process's
 130 effective group ID or one of its supplementary group IDs
 131 is restricted to a process with appropriate privileges.
 132 According to POSIX.1,
 133 this variable shall always be defined with a value other than \-1.
 134 The corresponding macro is
 135 .BR _POSIX_CHOWN_RESTRICTED .
 136 .IP
 137 If
 138 .I fd
 139 or
 140 .I path
 141 refers to a directory,
 142 then the return value applies to all files in that directory.
 143 .TP
 144 .B _PC_NO_TRUNC
 145 This returns nonzero if accessing filenames longer than
 146 .B _POSIX_NAME_MAX
 147 generates an error.
 148 The corresponding macro is
 149 .BR _POSIX_NO_TRUNC .
 150 .TP
 151 .B _PC_VDISABLE
 152 This returns nonzero if special character processing can be disabled, where
 153 .I fd
 154 or
 155 .I path
 156 must refer to a terminal.
 157 .SH RETURN VALUE
 158 The return value of these functions is one of the following:
 159 .IP * 3
 160 On error, \-1 is returned and
 161 .I errno
 162 is set to indicate the error
 163 (for example,
 164 .BR EINVAL ,
 165 indicating that
 166 .I name
 167 is invalid).
 168 .IP *
 169 If
 170 .I name
 171 corresponds to a maximum or minimum limit, and that limit is indeterminate,
 172 \-1 is returned and
 173 .I errno
 174 is not changed.
 175 (To distinguish an indeterminate limit from an error, set
 176 .I errno
 177 to zero before the call, and then check whether
 178 .I errno
 179 is nonzero when \-1 is returned.)
 180 .IP *
 181 If
 182 .I name
 183 corresponds to an option,
 184 a positive value is returned if the option is supported,
 185 and \-1 is returned if the option is not supported.
 186 .IP *
 187 Otherwise,
 188 the current value of the option or limit is returned.
 189 This value will not be more restrictive than
 190 the corresponding value that was described to the application in
 191 .I <unistd.h>
 192 or
 193 .I <limits.h>
 194 when the application was compiled.
 195 .SH ERRORS
 196 .TP
 197 .B EACCES
 198 .RB ( pathconf ())
 199 Search permission is denied for one of the directories in the path prefix of
 200 .IR path .
 201 .TP
 202 .B EBADF
 203 .RB ( fpathconf ())
 204 .I fd
 205 is not a valid file descriptor.
 206 .TP
 207 .B EINVAL
 208 .I name
 209 is invalid.
 210 .TP
 211 .B EINVAL
 212 The implementation does not support an association of
 213 .I name
 214 with the specified file.
 215 .TP
 216 .B ELOOP
 217 .RB ( pathconf ())
 218 Too many symbolic links were encountered while resolving
 219 .IR path .
 220 .TP
 221 .B ENAMETOOLONG
 222 .RB ( pathconf ())
 223 .I path
 224 is too long.
 225 .TP
 226 .B ENOENT
 227 .RB ( pathconf ())
 228 A component of
 229 .I path
 230 does not exist, or
 231 .I path
 232 is an empty string.
 233 .TP
 234 .B ENOTDIR
 235 .RB ( pathconf ())
 236 A component used as a directory in
 237 .I path
 238 is not in fact a directory.
 239 .SH ATTRIBUTES
 240 For an explanation of the terms used in this section, see
 241 .BR attributes (7).
 242 .ad l
 243 .nh
 244 .TS
 245 allbox;
 246 lbx lb lb
 247 l l l.
 248 Interface       Attribute       Value
 249 T{
 250 .BR fpathconf (),
 251 .BR pathconf ()
 252 T}      Thread safety   MT-Safe
 253 .TE
 254 .hy
 255 .ad
 256 .sp 1
 257 .SH STANDARDS
 258 POSIX.1-2001, POSIX.1-2008.
 259 .SH NOTES
 260 Files with name lengths longer than the value returned for
 261 .I name
 262 equal to
 263 .B _PC_NAME_MAX
 264 may exist in the given directory.
 265 .PP
 266 Some returned values may be huge; they are not suitable for allocating
 267 memory.
 268 .SH SEE ALSO
 269 .BR getconf (1),
 270 .BR open (2),
 271 .BR statfs (2),
 272 .BR confstr (3),
 273 .BR sysconf (3)