lib/libc/sys/fcntl.2

   1 .\" Copyright (c) 1983, 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 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
  29 .\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
  30 .\"
  31 .Dd January 12, 1994
  32 .Dt FCNTL 2
  33 .Os
  34 .Sh NAME
  35 .Nm fcntl
  36 .Nd file control
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In fcntl.h
  41 .Ft int
  42 .Fn fcntl "int fd" "int cmd" "..."
  43 .Sh DESCRIPTION
  44 .Fn Fcntl
  45 provides for control over descriptors.
  46 The argument
  47 .Fa fd
  48 is a descriptor to be operated on by
  49 .Fa cmd
  50 as described below.  Depending on the value of
  51 .Fa cmd ,
  52 .Nm
  53 can take an additional third argument
  54 .Fa "int arg" .
  55 .Bl -tag -width F_GETOWNX
  56 .It Dv F_DUPFD
  57 Return a new descriptor as follows:
  58 .Pp
  59 .Bl -bullet -compact -offset 4n
  60 .It
  61 Lowest numbered available descriptor greater than or equal to
  62 .Fa arg .
  63 .It
  64 Same object references as the original descriptor.
  65 .It
  66 New descriptor shares the same file offset if the object
  67 was a file.
  68 .It
  69 Same access mode (read, write or read/write).
  70 .It
  71 Same file status flags (i.e., both file descriptors
  72 share the same file status flags).
  73 .It
  74 The close-on-exec flag associated with the new file descriptor
  75 is set to remain open across
  76 .Xr execve 2
  77 system calls.
  78 .El
  79 .It Dv F_GETFD
  80 Get the close-on-exec flag associated with the file descriptor
  81 .Fa fd
  82 as
  83 .Dv FD_CLOEXEC .
  84 If the returned value ANDed with
  85 .Dv FD_CLOEXEC
  86 is 0,
  87 the file will remain open across
  88 .Fn exec ,
  89 otherwise the file will be closed upon execution of
  90 .Fn exec
  91 .Fa ( arg
  92 is ignored).
  93 .It Dv F_SETFD
  94 Set the close-on-exec flag associated with
  95 .Fa fd
  96 to
  97 .Fa arg ,
  98 where
  99 .Fa arg
 100 is either 0 or
 101 .Dv FD_CLOEXEC ,
 102 as described above.
 103 .It Dv F_GETFL
 104 Get descriptor status flags, as described below
 105 .Fa ( arg
 106 is ignored).
 107 .It Dv F_SETFL
 108 Set descriptor status flags to
 109 .Fa arg .
 110 .It Dv F_GETOWN
 111 Get the process ID or process group
 112 currently receiving
 113 .Dv SIGIO
 114 and
 115 .Dv SIGURG
 116 signals; process groups are returned
 117 as negative values
 118 .Fa ( arg
 119 is ignored).
 120 .It Dv F_SETOWN
 121 Set the process or process group
 122 to receive
 123 .Dv SIGIO
 124 and
 125 .Dv SIGURG
 126 signals;
 127 process groups are specified by supplying
 128 .Fa arg
 129 as negative, otherwise
 130 .Fa arg
 131 is interpreted as a process ID.
 132 .El
 133 .Pp
 134 The flags for the
 135 .Dv F_GETFL
 136 and
 137 .Dv F_SETFL
 138 flags are as follows:
 139 .Bl -tag -width O_NONBLOCKX
 140 .It Dv O_NONBLOCK
 141 Non-blocking I/O; if no data is available to a
 142 .Xr read 2
 143 call, or if a
 144 .Xr write 2
 145 operation would block,
 146 the read or write call returns -1 with the error
 147 .Er EAGAIN .
 148 .It Dv O_APPEND
 149 Force each write to append at the end of file;
 150 corresponds to the
 151 .Dv O_APPEND
 152 flag of
 153 .Xr open 2 .
 154 .It Dv O_DIRECT
 155 Minimize or eliminate the cache effects of reading and writing.  The system
 156 will attempt to avoid caching the data you read or write.  If it cannot
 157 avoid caching the data, it will minimize the impact the data has on the cache.
 158 Use of this flag can drastically reduce performance if not used with care.
 159 .It Dv O_ASYNC
 160 Enable the
 161 .Dv SIGIO
 162 signal to be sent to the process group
 163 when I/O is possible, e.g.,
 164 upon availability of data to be read.
 165 .El
 166 .Pp
 167 Several commands are available for doing advisory file locking;
 168 they all operate on the following structure:
 169 .Bd -literal
 170 struct flock {
 171         off_t   l_start;        /* starting offset */
 172         off_t   l_len;          /* len = 0 means until end of file */
 173         pid_t   l_pid;          /* lock owner */
 174         short   l_type;         /* lock type: read/write, etc. */
 175         short   l_whence;       /* type of l_start */
 176 };
 177 .Ed
 178 The commands available for advisory record locking are as follows:
 179 .Bl -tag -width F_SETLKWX
 180 .It Dv F_GETLK
 181 Get the first lock that blocks the lock description pointed to by the
 182 third argument,
 183 .Fa arg ,
 184 taken as a pointer to a
 185 .Fa "struct flock"
 186 (see above).
 187 The information retrieved overwrites the information passed to
 188 .Fn fcntl
 189 in the
 190 .Fa flock
 191 structure.
 192 If no lock is found that would prevent this lock from being created,
 193 the structure is left unchanged by this function call except for the
 194 lock type which is set to
 195 .Dv F_UNLCK .
 196 .It Dv F_SETLK
 197 Set or clear a file segment lock according to the lock description
 198 pointed to by the third argument,
 199 .Fa arg ,
 200 taken as a pointer to a
 201 .Fa "struct flock"
 202 (see above).
 203 .Dv F_SETLK
 204 is used to establish shared (or read) locks
 205 .Pq Dv F_RDLCK
 206 or exclusive (or write) locks,
 207 .Pq Dv F_WRLCK ,
 208 as well as remove either type of lock
 209 .Pq Dv F_UNLCK .
 210 If a shared or exclusive lock cannot be set,
 211 .Fn fcntl
 212 returns immediately with
 213 .Er EAGAIN .
 214 .It Dv F_SETLKW
 215 This command is the same as
 216 .Dv F_SETLK
 217 except that if a shared or exclusive lock is blocked by other locks,
 218 the process waits until the request can be satisfied.
 219 If a signal that is to be caught is received while
 220 .Fn fcntl
 221 is waiting for a region, the
 222 .Fn fcntl
 223 will be interrupted if the signal handler has not specified the
 224 .Dv SA_RESTART
 225 (see
 226 .Xr sigaction 2 ) .
 227 .El
 228 .Pp
 229 When a shared lock has been set on a segment of a file,
 230 other processes can set shared locks on that segment
 231 or a portion of it.
 232 A shared lock prevents any other process from setting an exclusive
 233 lock on any portion of the protected area.
 234 A request for a shared lock fails if the file descriptor was not
 235 opened with read access.
 236 .Pp
 237 An exclusive lock prevents any other process from setting a shared lock or
 238 an exclusive lock on any portion of the protected area.
 239 A request for an exclusive lock fails if the file was not
 240 opened with write access.
 241 .Pp
 242 The value of
 243 .Fa l_whence
 244 is
 245 .Dv SEEK_SET ,
 246 .Dv SEEK_CUR ,
 247 or
 248 .Dv SEEK_END
 249 to indicate that the relative offset,
 250 .Fa l_start
 251 bytes, will be measured from the start of the file,
 252 current position, or end of the file, respectively.
 253 The value of
 254 .Fa l_len
 255 is the number of consecutive bytes to be locked.
 256 If
 257 .Fa l_len
 258 is negative, the result is undefined.
 259 The
 260 .Fa l_pid
 261 field is only used with
 262 .Dv F_GETLK
 263 to return the process ID of the process holding a blocking lock.
 264 After a successful
 265 .Dv F_GETLK
 266 request, the value of
 267 .Fa l_whence
 268 is
 269 .Dv SEEK_SET .
 270 .Pp
 271 Locks may start and extend beyond the current end of a file,
 272 but may not start or extend before the beginning of the file.
 273 A lock is set to extend to the largest possible value of the
 274 file offset for that file if
 275 .Fa l_len
 276 is set to zero.
 277 If
 278 .Fa l_whence
 279 and
 280 .Fa l_start
 281 point to the beginning of the file, and
 282 .Fa l_len
 283 is zero, the entire file is locked.
 284 If an application wishes only to do entire file locking, the
 285 .Xr flock 2
 286 system call is much more efficient.
 287 .Pp
 288 There is at most one type of lock set for each byte in the file.
 289 Before a successful return from an
 290 .Dv F_SETLK
 291 or an
 292 .Dv F_SETLKW
 293 request when the calling process has previously existing locks
 294 on bytes in the region specified by the request,
 295 the previous lock type for each byte in the specified
 296 region is replaced by the new lock type.
 297 As specified above under the descriptions
 298 of shared locks and exclusive locks, an
 299 .Dv F_SETLK
 300 or an
 301 .Dv F_SETLKW
 302 request fails or blocks respectively when another process has existing
 303 locks on bytes in the specified region and the type of any of those
 304 locks conflicts with the type specified in the request.
 305 .Pp
 306 This interface follows the completely stupid semantics of System V and
 307 .St -p1003.1-88
 308 that require that all locks associated with a file for a given process are
 309 removed when
 310 .Em any
 311 file descriptor for that file is closed by that process.
 312 This semantic means that applications must be aware of any files that
 313 a subroutine library may access.
 314 For example if an application for updating the password file locks the
 315 password file database while making the update, and then calls
 316 .Xr getpwnam 3
 317 to retrieve a record,
 318 the lock will be lost because
 319 .Xr getpwnam 3
 320 opens, reads, and closes the password database.
 321 The database close will release all locks that the process has
 322 associated with the database, even if the library routine never
 323 requested a lock on the database.
 324 Another minor semantic problem with this interface is that
 325 locks are not inherited by a child process created using the
 326 .Xr fork 2
 327 function.
 328 The
 329 .Xr flock 2
 330 interface has much more rational last close semantics and
 331 allows locks to be inherited by child processes.
 332 .Xr Flock 2
 333 is recommended for applications that want to ensure the integrity
 334 of their locks when using library routines or wish to pass locks
 335 to their children.
 336 Note that
 337 .Xr flock 2
 338 and
 339 .Xr fcntl 2
 340 locks may be safely used concurrently but
 341 .Fn fcntl F_GETLK
 342 returns \-1 in
 343 .Fa l_pid
 344 if the process holding a blocking lock previously locked the
 345 file descriptor by
 346 .Xr flock 2 .
 347 .Pp
 348 All locks associated with a file for a given process are
 349 removed when the process terminates.
 350 .Pp
 351 All locks obtained before a call to
 352 .Xr execve 2
 353 remain in effect until the new program releases them.
 354 If the new program does not know about the locks, they will not be
 355 released until the program exits.
 356 .Pp
 357 A potential for deadlock occurs if a process controlling a locked region
 358 is put to sleep by attempting to lock the locked region of another process.
 359 This implementation detects that sleeping until a locked region is unlocked
 360 would cause a deadlock and fails with an
 361 .Er EDEADLK
 362 error.
 363 .Sh RETURN VALUES
 364 Upon successful completion, the value returned depends on
 365 .Fa cmd
 366 as follows:
 367 .Bl -tag -width F_GETOWNX -offset indent
 368 .It Dv F_DUPFD
 369 A new file descriptor.
 370 .It Dv F_GETFD
 371 Value of flag (only the low-order bit is defined).
 372 .It Dv F_GETFL
 373 Value of flags.
 374 .It Dv F_GETOWN
 375 Value of file descriptor owner.
 376 .It other
 377 Value other than -1.
 378 .El
 379 .Pp
 380 Otherwise, a value of -1 is returned and
 381 .Va errno
 382 is set to indicate the error.
 383 .Sh ERRORS
 384 .Fn Fcntl
 385 will fail if:
 386 .Bl -tag -width Er
 387 .It Bq Er EAGAIN
 388 The argument
 389 .Fa cmd
 390 is
 391 .Dv F_SETLK ,
 392 the type of lock
 393 .Pq Fa l_type
 394 is a shared lock
 395 .Pq Dv F_RDLCK
 396 or exclusive lock
 397 .Pq Dv F_WRLCK ,
 398 and the segment of a file to be locked is already
 399 exclusive-locked by another process;
 400 or the type is an exclusive lock and some portion of the
 401 segment of a file to be locked is already shared-locked or
 402 exclusive-locked by another process.
 403 .It Bq Er EBADF
 404 .Fa \&Fd
 405 is not a valid open file descriptor.
 406 .Pp
 407 The argument
 408 .Fa cmd
 409 is
 410 .Dv F_SETLK
 411 or
 412 .Dv F_SETLKW ,
 413 the type of lock
 414 .Pq Fa l_type
 415 is a shared lock
 416 .Pq Dv F_RDLCK ,
 417 and
 418 .Fa fd
 419 is not a valid file descriptor open for reading.
 420 .Pp
 421 The argument
 422 .Fa cmd
 423 is
 424 .Dv F_SETLK
 425 or
 426 .Dv F_SETLKW ,
 427 the type of lock
 428 .Pq Fa l_type
 429 is an exclusive lock
 430 .Pq Dv F_WRLCK ,
 431 and
 432 .Fa fd
 433 is not a valid file descriptor open for writing.
 434 .It Bq Er EDEADLK
 435 The argument
 436 .Fa cmd
 437 is
 438 .Dv F_SETLKW ,
 439 and a deadlock condition was detected.
 440 .It Bq Er EINTR
 441 The argument
 442 .Fa cmd
 443 is
 444 .Dv F_SETLKW ,
 445 and the function was interrupted by a signal.
 446 .It Bq Er EINVAL
 447 .Fa Cmd
 448 is
 449 .Dv F_DUPFD
 450 and
 451 .Fa arg
 452 is negative or greater than the maximum allowable number
 453 (see
 454 .Xr getdtablesize 2 ) .
 455 .Pp
 456 The argument
 457 .Fa cmd
 458 is
 459 .Dv F_GETLK ,
 460 .Dv F_SETLK ,
 461 or
 462 .Dv F_SETLKW
 463 and the data to which
 464 .Fa arg
 465 points is not valid, or
 466 .Fa fd
 467 refers to a file that does not support locking.
 468 .It Bq Er EMFILE
 469 The argument
 470 .Fa cmd
 471 is
 472 .Dv F_DUPFD
 473 and the maximum number of file descriptors permitted for the
 474 process are already in use,
 475 or no file descriptors greater than or equal to
 476 .Fa arg
 477 are available.
 478 .It Bq Er ENOLCK
 479 The argument
 480 .Fa cmd
 481 is
 482 .Dv F_SETLK
 483 or
 484 .Dv F_SETLKW ,
 485 and satisfying the lock or unlock request would result in the
 486 number of locked regions in the system exceeding a system-imposed limit.
 487 .It Bq Er EPERM
 488 .Fa Cmd
 489 is
 490 .Dv F_SETOWN
 491 and
 492 the process ID or process group given as an argument is in a
 493 different session than the caller.
 494 .It Bq Er ESRCH
 495 .Fa Cmd
 496 is
 497 .Dv F_SETOWN
 498 and
 499 the process ID given as argument is not in use.
 500 .El
 501 .Pp
 502 In addition, if
 503 .Fa fd
 504 refers to a descriptor open on a terminal device (as opposed to a
 505 descriptor open on a socket), a
 506 .Fa cmd
 507 of
 508 .Dv F_SETOWN
 509 can fail for the same reasons as in
 510 .Xr tcsetpgrp 3 ,
 511 and a
 512 .Fa cmd
 513 of
 514 .Dv F_GETOWN
 515 for the reasons as stated in
 516 .Xr tcgetpgrp 3 .
 517 .Sh SEE ALSO
 518 .Xr close 2 ,
 519 .Xr execve 2 ,
 520 .Xr flock 2 ,
 521 .Xr getdtablesize 2 ,
 522 .Xr open 2 ,
 523 .Xr sigaction 2 ,
 524 .Xr tcgetpgrp 3 ,
 525 .Xr tcsetpgrp 3
 526 .Sh HISTORY
 527 The
 528 .Fn fcntl
 529 function call appeared in
 530 .Bx 4.2 .