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