lib/libcr/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: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
  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 .Fn Fcntl
  49 provides for control over descriptors.
  50 The argument
  51 .Fa fd
  52 is a descriptor to be operated on by
  53 .Fa cmd
  54 as described below.  Depending on the value of
  55 .Fa cmd ,
  56 .Nm
  57 can take an additional third argument
  58 .Fa "int arg" .
  59 .Bl -tag -width F_GETOWNX
  60 .It Dv F_DUPFD
  61 Return a new descriptor as follows:
  62 .Pp
  63 .Bl -bullet -compact -offset 4n
  64 .It
  65 Lowest numbered available descriptor greater than or equal to
  66 .Fa arg .
  67 .It
  68 Same object references as the original descriptor.
  69 .It
  70 New descriptor shares the same file offset if the object
  71 was a file.
  72 .It
  73 Same access mode (read, write or read/write).
  74 .It
  75 Same file status flags (i.e., both file descriptors
  76 share the same file status flags).
  77 .It
  78 The close-on-exec flag associated with the new file descriptor
  79 is set to remain open across
  80 .Xr execve 2
  81 system calls.
  82 .El
  83 .It Dv F_GETFD
  84 Get the close-on-exec flag associated with the file descriptor
  85 .Fa fd
  86 as
  87 .Dv FD_CLOEXEC .
  88 If the returned value ANDed with
  89 .Dv FD_CLOEXEC
  90 is 0,
  91 the file will remain open across
  92 .Fn exec ,
  93 otherwise the file will be closed upon execution of
  94 .Fn exec
  95 .Fa ( arg
  96 is ignored).
  97 .It Dv F_SETFD
  98 Set the close-on-exec flag associated with
  99 .Fa fd
 100 to
 101 .Fa arg ,
 102 where
 103 .Fa arg
 104 is either 0 or
 105 .Dv FD_CLOEXEC ,
 106 as described above.
 107 .It Dv F_GETFL
 108 Get descriptor status flags, as described below
 109 .Fa ( arg
 110 is ignored).
 111 .It Dv F_SETFL
 112 Set descriptor status flags to
 113 .Fa arg .
 114 .It Dv F_GETOWN
 115 Get the process ID or process group
 116 currently receiving
 117 .Dv SIGIO
 118 and
 119 .Dv SIGURG
 120 signals; process groups are returned
 121 as negative values
 122 .Fa ( arg
 123 is ignored).
 124 .It Dv F_SETOWN
 125 Set the process or process group
 126 to receive
 127 .Dv SIGIO
 128 and
 129 .Dv SIGURG
 130 signals;
 131 process groups are specified by supplying
 132 .Fa arg
 133 as negative, otherwise
 134 .Fa arg
 135 is interpreted as a process ID.
 136 .El
 137 .Pp
 138 The flags for the
 139 .Dv F_GETFL
 140 and
 141 .Dv F_SETFL
 142 flags are as follows:
 143 .Bl -tag -width O_NONBLOCKX
 144 .It Dv O_NONBLOCK
 145 Non-blocking I/O; if no data is available to a
 146 .Xr read 2
 147 call, or if a
 148 .Xr write 2
 149 operation would block,
 150 the read or write call returns -1 with the error
 151 .Er EAGAIN .
 152 .It Dv O_APPEND
 153 Force each write to append at the end of file;
 154 corresponds to the
 155 .Dv O_APPEND
 156 flag of
 157 .Xr open 2 .
 158 .It Dv O_DIRECT
 159 Minimize or eliminate the cache effects of reading and writing.  The system
 160 will attempt to avoid caching the data you read or write.  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 function 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, the result is undefined.
 263 The
 264 .Fa l_pid
 265 field is only used with
 266 .Dv F_GETLK
 267 to return the process ID of the process holding a blocking lock.
 268 After a successful
 269 .Dv F_GETLK
 270 request, the value of
 271 .Fa l_whence
 272 is
 273 .Dv SEEK_SET .
 274 .Pp
 275 Locks may start and extend beyond the current end of a file,
 276 but may not start or extend before the beginning of the file.
 277 A lock is set to extend to the largest possible value of the
 278 file offset for that file if
 279 .Fa l_len
 280 is set to zero.
 281 If
 282 .Fa l_whence
 283 and
 284 .Fa l_start
 285 point to the beginning of the file, and
 286 .Fa l_len
 287 is zero, the entire file is locked.
 288 If an application wishes only to do entire file locking, the
 289 .Xr flock 2
 290 system call is much more efficient.
 291 .Pp
 292 There is at most one type of lock set for each byte in the file.
 293 Before a successful return from an
 294 .Dv F_SETLK
 295 or an
 296 .Dv F_SETLKW
 297 request when the calling process has previously existing locks
 298 on bytes in the region specified by the request,
 299 the previous lock type for each byte in the specified
 300 region is replaced by the new lock type.
 301 As specified above under the descriptions
 302 of shared locks and exclusive locks, an
 303 .Dv F_SETLK
 304 or an
 305 .Dv F_SETLKW
 306 request fails or blocks respectively when another process has existing
 307 locks on bytes in the specified region and the type of any of those
 308 locks conflicts with the type specified in the request.
 309 .Pp
 310 This interface follows the completely stupid semantics of System V and
 311 .St -p1003.1-88
 312 that require that all locks associated with a file for a given process are
 313 removed when
 314 .Em any
 315 file descriptor for that file is closed by that process.
 316 This semantic means that applications must be aware of any files that
 317 a subroutine library may access.
 318 For example if an application for updating the password file locks the
 319 password file database while making the update, and then calls
 320 .Xr getpwnam 3
 321 to retrieve a record,
 322 the lock will be lost because
 323 .Xr getpwnam 3
 324 opens, reads, and closes the password database.
 325 The database close will release all locks that the process has
 326 associated with the database, even if the library routine never
 327 requested a lock on the database.
 328 Another minor semantic problem with this interface is that
 329 locks are not inherited by a child process created using the
 330 .Xr fork 2
 331 function.
 332 The
 333 .Xr flock 2
 334 interface has much more rational last close semantics and
 335 allows locks to be inherited by child processes.
 336 .Xr Flock 2
 337 is recommended for applications that want to ensure the integrity
 338 of their locks when using library routines or wish to pass locks
 339 to their children.
 340 Note that
 341 .Xr flock 2
 342 and
 343 .Xr fcntl 2
 344 locks may be safely used concurrently but
 345 .Fn fcntl F_GETLK
 346 returns \-1 in
 347 .Fa l_pid
 348 if the process holding a blocking lock previously locked the
 349 file descriptor by
 350 .Xr flock 2 .
 351 .Pp
 352 All locks associated with a file for a given process are
 353 removed when the process terminates.
 354 .Pp
 355 All locks obtained before a call to
 356 .Xr execve 2
 357 remain in effect until the new program releases them.
 358 If the new program does not know about the locks, they will not be
 359 released until the program exits.
 360 .Pp
 361 A potential for deadlock occurs if a process controlling a locked region
 362 is put to sleep by attempting to lock the locked region of another process.
 363 This implementation detects that sleeping until a locked region is unlocked
 364 would cause a deadlock and fails with an
 365 .Er EDEADLK
 366 error.
 367 .Sh RETURN VALUES
 368 Upon successful completion, the value returned depends on
 369 .Fa cmd
 370 as follows:
 371 .Bl -tag -width F_GETOWNX -offset indent
 372 .It Dv F_DUPFD
 373 A new file descriptor.
 374 .It Dv F_GETFD
 375 Value of flag (only the low-order bit is defined).
 376 .It Dv F_GETFL
 377 Value of flags.
 378 .It Dv F_GETOWN
 379 Value of file descriptor owner.
 380 .It other
 381 Value other than -1.
 382 .El
 383 .Pp
 384 Otherwise, a value of -1 is returned and
 385 .Va errno
 386 is set to indicate the error.
 387 .Sh ERRORS
 388 .Fn Fcntl
 389 will fail if:
 390 .Bl -tag -width Er
 391 .It Bq Er EAGAIN
 392 The argument
 393 .Fa cmd
 394 is
 395 .Dv F_SETLK ,
 396 the type of lock
 397 .Pq Fa l_type
 398 is a shared lock
 399 .Pq Dv F_RDLCK
 400 or exclusive lock
 401 .Pq Dv F_WRLCK ,
 402 and the segment of a file to be locked is already
 403 exclusive-locked by another process;
 404 or the type is an exclusive lock and some portion of the
 405 segment of a file to be locked is already shared-locked or
 406 exclusive-locked by another process.
 407 .It Bq Er EBADF
 408 .Fa \&Fd
 409 is not a valid open file descriptor.
 410 .Pp
 411 The argument
 412 .Fa cmd
 413 is
 414 .Dv F_SETLK
 415 or
 416 .Dv F_SETLKW ,
 417 the type of lock
 418 .Pq Fa l_type
 419 is a shared lock
 420 .Pq Dv F_RDLCK ,
 421 and
 422 .Fa fd
 423 is not a valid file descriptor open for reading.
 424 .Pp
 425 The argument
 426 .Fa cmd
 427 is
 428 .Dv F_SETLK
 429 or
 430 .Dv F_SETLKW ,
 431 the type of lock
 432 .Pq Fa l_type
 433 is an exclusive lock
 434 .Pq Dv F_WRLCK ,
 435 and
 436 .Fa fd
 437 is not a valid file descriptor open for writing.
 438 .It Bq Er EDEADLK
 439 The argument
 440 .Fa cmd
 441 is
 442 .Dv F_SETLKW ,
 443 and a deadlock condition was detected.
 444 .It Bq Er EINTR
 445 The argument
 446 .Fa cmd
 447 is
 448 .Dv F_SETLKW ,
 449 and the function was interrupted by a signal.
 450 .It Bq Er EINVAL
 451 .Fa Cmd
 452 is
 453 .Dv F_DUPFD
 454 and
 455 .Fa arg
 456 is negative or greater than the maximum allowable number
 457 (see
 458 .Xr getdtablesize 2 ) .
 459 .Pp
 460 The argument
 461 .Fa cmd
 462 is
 463 .Dv F_GETLK ,
 464 .Dv F_SETLK ,
 465 or
 466 .Dv F_SETLKW
 467 and the data to which
 468 .Fa arg
 469 points is not valid, or
 470 .Fa fd
 471 refers to a file that does not support locking.
 472 .It Bq Er EMFILE
 473 The argument
 474 .Fa cmd
 475 is
 476 .Dv F_DUPFD
 477 and the maximum number of file descriptors permitted for the
 478 process are already in use,
 479 or no file descriptors greater than or equal to
 480 .Fa arg
 481 are available.
 482 .It Bq Er ENOLCK
 483 The argument
 484 .Fa cmd
 485 is
 486 .Dv F_SETLK
 487 or
 488 .Dv F_SETLKW ,
 489 and satisfying the lock or unlock request would result in the
 490 number of locked regions in the system exceeding a system-imposed limit.
 491 .It Bq Er EPERM
 492 .Fa Cmd
 493 is
 494 .Dv F_SETOWN
 495 and
 496 the process ID or process group given as an argument is in a
 497 different session than the caller.
 498 .It Bq Er ESRCH
 499 .Fa Cmd
 500 is
 501 .Dv F_SETOWN
 502 and
 503 the process ID given as argument is not in use.
 504 .El
 505 .Pp
 506 In addition, if
 507 .Fa fd
 508 refers to a descriptor open on a terminal device (as opposed to a
 509 descriptor open on a socket), a
 510 .Fa cmd
 511 of
 512 .Dv F_SETOWN
 513 can fail for the same reasons as in
 514 .Xr tcsetpgrp 3 ,
 515 and a
 516 .Fa cmd
 517 of
 518 .Dv F_GETOWN
 519 for the reasons as stated in
 520 .Xr tcgetpgrp 3 .
 521 .Sh SEE ALSO
 522 .Xr close 2 ,
 523 .Xr execve 2 ,
 524 .Xr flock 2 ,
 525 .Xr getdtablesize 2 ,
 526 .Xr open 2 ,
 527 .Xr sigvec 2 ,
 528 .Xr tcgetpgrp 3 ,
 529 .Xr tcsetpgrp 3
 530 .Sh HISTORY
 531 The
 532 .Fn fcntl
 533 function call appeared in
 534 .Bx 4.2 .