.\" Hey Emacs! This file is -*- nroff -*- source. .\" .\" This manpage is Copyright (C) 1992 Drew Eckhardt; .\" 1993 Michael Haardt, Ian Jackson. .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Modified Sat Jul 24 13:39:26 1993 by Rik Faith .\" Modified Tue Sep 26 21:47:21 1995 by Andries Brouwer .\" and once more on 960413. .\" .TH FCNTL 2 "26 September 1995" Linux "Linux Programmer's Manual" .SH NAME fcntl \- manipulate file descriptor .SH SYNOPSIS .nf .B #include .B #include .sp .BI "int fcntl(int " fd ", int " cmd ); .BI "int fcntl(int " fd ", int " cmd ", long " arg ); .fi .SH DESCRIPTION .B fcntl performs one of various miscellaneous operations on .IR fd . The operation in question is determined by .IR cmd : .TP 0.9i .B F_DUPFD Makes .I arg be a copy of .IR fd , closing .I fd first if necessary. .sp The same functionality can be more easily achieved by using .BR dup2 (2). .sp The old and new descriptors may be used interchangeably. They share locks, file position pointers and flags; for example, if the file position is modified by using .B lseek on one of the descriptors, the position is also changed for the other. .sp The two descriptors do not share the close-on-exec flag, however. The close-on-exec flag of the copy is off, meaning that it will be closed on exec. .sp On success, the new descriptor is returned. .TP .B F_GETFD Read the close-on-exec flag. If the low-order bit is 0, the file will remain open across .BR exec , otherwise it will be closed. .TP .B F_SETFD Set the close-on-exec flag to the value specified by .I arg (only the least significant bit is used). .TP .B F_GETFL Read the descriptor's flags (all flags (as set by .BR open (2)) are returned). .TP .B F_SETFL Set the descriptor's flags to the value specified by .IR arg . Only .BR O_APPEND " and " O_NONBLOCK may be set. .sp The flags are shared between copies (made with .B dup etc.) of the same file descriptor. .sp The flags and their semantics are described in .BR open (2). .TP .BR F_GETLK ", " F_SETLK " and " F_SETLKW Manage discretionary file locks. The third argument .I arg is a pointer to a struct flock (that may be overwritten by this call). .TP .B F_GETLK Return the flock structure that prevents us from obtaining the lock, or set the .B l_type field of the lock to .B F_UNLCK if there is no obstruction. .TP .B F_SETLK The lock is set (when .B l_type is .B F_RDLCK or .BR F_WRLCK ) or cleared (when it is .BR F_UNLCK ). If the lock is held by someone else, this call returns -1 and sets .I errno to .B EACCES or .BR EAGAIN . .TP .B F_SETLKW Like .BR F_SETLK , but instead of returning an error we wait for the lock to be released. .TP .B F_GETOWN Get the process ID (or process group) of the owner of a socket. .sp Process groups are returned as negative values. .TP .B F_SETOWN Set the process or process group that owns a socket. .sp For these commands, ownership means receiving .B SIGIO or .B SIGURG signals. .sp Process groups are specified using negative values. .SH "RETURN VALUE" The return value depends on the operation: .TP 0.9i .B F_DUPFD The new descriptor. .TP .B F_GETFD Value of flag. .TP .B F_GETFL Value of flags. .TP .B F_GETOWN Value of descriptor owner. .PP On error, \-1 is returned, and .I errno is set appropriately. .SH ERRORS .TP 0.9i .B EACCES Operation is prohibited by locks held by other processes. .TP .B EAGAIN Operation is prohibited because the file has been memory-mapped by another process. .TP .B EDEADLK Specified write lock operation would cause a deadlock. .TP .B EBADF .I fd is not an open file descriptor. .TP .B EINVAL For .BR F_DUPFD , .I arg is negative or is greater than the maximum allowable value. .TP .B EMFILE For .BR F_DUPFD , the process already has the maximum number of file descriptors open. .TP .B ENOLCK Too many segment locks open, lock table is full. .SH NOTES The errors returned by .B dup2 are different from those returned by .BR F_DUPFD . .SH "CONFORMING TO" SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are specified in POSIX.1; F_GETOWN and F_SETOWN are BSDisms not supported in SVr4. The flags legal for F_GETFL/F_SETFL are those supported by .BR open (2) and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY, and O_RDWR are specified in POSIX.1. SVr4 supports several other options and flags not documented here. .PP POSIX.1 documents an additional EINTR condition. SVr4 documents additional EFAULT, EINTR, EIO, ENOLINK and EOVERFLOW error conditions. .SH "SEE ALSO" .BR dup2 (2), .BR open (2), .BR socket (2), .BR flock (2)