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