OSF  —  Environment_Note_Added

NAME

fcntl, dup, dup2 −   Controls open file descriptors

SYNOPSIS

#include <fcntl.h> #include <sys/types.h> #include <unistd.h> int fcntl (
int filedes,
int request [ ,
int argument | struct flock ∗argument  ]  ); int dup(
int filedes ); int dup2(
int old,
int new );

PARAMETERS

filedesSpecifies an open file descriptor obtained from a successful open(), fcntl(), or pipe() function. 

requestSpecifies the operation to be performed. 

argumentSpecifies a variable that depends on the value of the request parameter. 

oldSpecifies an open file descriptor. 

newSpecifies an open file descriptor that is returned by the dup2() function. 

DESCRIPTION

The fcntl() function performs controlling operations on the open file specified by the filedes parameter. 

When the fcntl(), dup() and dup2() functions need to block, only the calling thread is suspended rather than all threads in the calling process. 

The following are values for the request parameter:

F_DUPFDReturns a new file descriptor as follows:

       •Lowest numbered available file descriptor greater than or equal to the argument parameter, taken as type int. 

       •Same object references as the original file. 

       •Same file pointer as the original file.  (That is, both file descriptors share one file pointer if the object is a file). 

       •Same access mode (read, write, or read-write). 

       •Same file status flags.  (That is, both file descriptors share the same file status flags). 

       •The close-on-exec flag (FD_CLOEXEC bit) associated with the new file descriptor is cleared so that the file will remain open across exec functions. 

F_GETFDGets the value of the close-on-exec flag associated with the file descriptor filedes.  File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file.  The argument parameter is ignored. 

F_SETFDSets the close-on-exec flag associated with the filedes parameter to the value of the argument parameter, taken as type int.  If the argument parameter is 0 (zero), the file remains open across the exec functions.  If the argument parameter is FD_CLOEXEC, the file is closed on successful execution of the next exec function. 

F_GETFLGets the file status flags and file access modes for the file referred to by the filedes parameter.  The file access modes can be extracted by using the mask O_ACCMODE on the return value.  File status flags and file access modes are associated with the file description and do not affect other file descriptors that refer to the same file with different open file descriptions.  The argument parameter is ignored. 

F_SETFLSets the file status flags to the argument parameter, taken as type int, for the file to which the filedes parameter refers.  The file access mode is not changed. 

F_GETOWN
Gets the process ID or process group currently receiving SIGIO and SIGURG signals. Process groups are returned as negative values.

F_SETOWNSets the process or process group to receive SIGIO and SIGURG signals.  Process groups are specified by supplying the argument parameter as negative; otherwise the argument parameter, taken as type int, is interpreted as a process ID. 

The following values for the request parameter are available for record locking:

F_GETLKGets the first lock that blocks the lock description pointed to by the argument parameter, taken as a pointer to type struct flock.  The information retrieved overwrites the information passed to the fcntl() function in the flock structure.  If no lock is found that would prevent this lock from being created, then the structure is left unchanged except for the lock type, which is set to F_UNLCK. 

F_SETLKSets or clears a file segment lock according to the lock description pointed to by argument, taken as a pointer to type struct flock.  F_SETLK is used to establish shared locks (F_RDLCK), or exclusive locks (F_WRLCK), as well as remove either type of lock (F_UNLCK).   If a shared (read) or exclusive (write) lock cannot be set, the fcntl() function returns immediately with a value of -1. 

F_SETLKWSame as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the process will wait until it is unblocked.  If a signal is received while fcntl() is waiting for a region, the function is interrupted, -1 is returned, and errno is set to [EINTR]. 

The O_NDELAY and O_NONBLOCK requests affect only operations against file descriptors derived from the same open() function.  In BSD, these apply to all file descriptors that refer to the object. 

When a shared lock is set on a segment of a file, other processes are able to set shared locks on that segment or a portion of it.  A shared lock prevents any other process from setting an exclusive lock on any portion of the protected area.  A request for a shared lock fails if the file descriptor was not opened with read access. 

An exclusive lock prevents any other process from setting a shared lock or an exclusive lock on any portion of the protected area.  A request for an exclusive lock fails if the file descriptor was not opened with write access. 

The flock() structure describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len) and process ID (l_pid) of the segment of the file to be affected. 

The value of l_whence is set to SEEK_SET, SEEK_CUR or SEEK_END, to indicate that the relative offset l_start bytes is measured from the start of the file, from the current position, or from the end of the file, respectively.  The value of l_len is the number of consecutive bytes to be locked.  The l_len value may be negative (where the definition of off_t permits negative values of l_len).  The l_pid field is only used with F_GETLK to return the process ID of the process holding a blocking lock. After a successful F_GETLK request, the value of l_whence becomes SEEK_SET. 

If l_len is positive, the area affected starts at l_start and ends at l_start + l_len − 1.  If l_len is negative, the area affected starts at l_start + l_len and ends at l_start − 1.  Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file.  If l_len is set to 0 (zero), a lock may be set to always extend to the largest possible value of the file offset for that file.  If such a lock also has l_start set to 0 (zero) and l_whence is set to SEEK_SET, the whole file is locked.  Changing or unlocking a portion from the middle of a larger locked segment leaves a smaller segment at either end.  Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect.  All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or the process holding that file descriptor terminates.  Locks are not inherited by a child process in a fork() function. 

If a regular file has enforced record locking enabled, record locks on the file will affect calls to other calls, including creat(), open(), read(), write(), truncate(), and ftruncate(). 

A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock another process’ locked region.  If the system detects that sleeping until a locked region is unlocked would cause a deadlock, the fcntl() function fails with an [EDEADLK] error. 

NOTES

The dup(filedes) function is equivalent to fnctl(filedes, F_DUPFD, 0). 

The dup2(oldfiledes, newfiledes) function has similar functionality to:
    close(newfiledes)
    fcntl(oldfiledes, F_DUPFD, newfiledes)

The file locks set by the fcntl() and lockf() functions do not interact in any way with the file locks set by the flock()function.  If a process sets an exclusive lock on a file using the fcntl() or lockf() function, the lock will not affect any process that is setting or clearing locks on the same file using the flock() function.  It is therefore possible for an inconsistency to arise if a file is locked by different processes using flock() and fcntl().  (The fcntl() and lockf() functions use the same mechanism for record locking.) 

AES Support Level:
Full use

RETURN VALUES

Upon successful completion, the value returned depends on the value of the request parameter as follows:

F_DUPFDReturns a new file descriptor. 

F_GETFDReturns FD_CLOEXEC or 0 (zero). 

F_SETFDReturns a value other than -1. 

F_GETFLReturns the value of file status flags and access modes.  (The return value will not be negative.) 

F_SETFLReturns a value other than -1. 

F_GETOWN
Returns the value of descriptor owner.

F_GETLKReturns a value other than -1. 

F_SETLKReturns a value other than -1. 

F_SETLKWReturns a value other than -1. 

If the fcntl() function fails, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the fcntl() function fails, errno may be set to one of the following values:

[EBADF]The filedes parameter is not a valid open file descriptor. 

[EBADF]The request parameter is F_SETLK or F_SETLKW, the type of lock (l_type) is a shared lock (F_RDLCK), and filedes is not a valid file descriptor open for reading. 

[EBADF]The type of lock (l_type) is an exclusive lock (F_WRLCK), and filedes is not a valid file descriptor open for writing. 

[EMFILE]The request parameter is F_DUPFD and OPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal to argument are available. 

[EINVAL]The request parameter is F_DUPFD and the argument parameter is negative or greater than or equal to OPEN_MAX. 

[EINVAL]An illegal value was provided for the request parameter. 

[EINVAL]The request parameter is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by argument is invalid, or filedes refers to a file that does not support locking. 

[EFAULT]The argument parameter is an invalid address. 

[ESRCH]The value of the request parameter is F_SETOWN and the process ID given as argument is not in use. 

[EAGAIN]The request parameter is F_SETLK, the type of lock (l_type) is a shared (F_RDLCK) or exclusive (F_WRLCK) lock, and the segment of a file to be locked is already exclusive-locked by another process. 

[EAGAIN]The request parameter is F_SETLK, and the type is an exclusive lock and some portion of the segment of a file to be locked is already shared-locked or exclusive-locked by another process. 

[EINTR]The request parameter is F_SETLKW and the fcntl() function was interrupted by a signal which was caught. 

[ENOLCK]The request parameter is F_SETLK or F_SETLKW and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit. 

[EDEADLK]The request parameter is F_SETLKW, the lock is blocked by some lock from another process and putting the calling process to sleep, and waiting for that lock to become free would cause a deadlock. 

If the dup() or dup2() function fails, errno may be set to one of the following values:

[EBADF]The filedes or old parameter is not a valid open file descriptor or the new parameter file descriptor is negative or greater than OPEN_MAX. 

[EMFILE]The number of file descriptors exceeds OPEN_MAX or there is no file descriptor above the value of the new parameter. 

[EINTR]The dup2() function was interrupted by a signal which was caught. 

[EACCES]Cmd is F_SETLK the type of lock (l_type) is a read (F_RDLCK) lock and the segment of a file to be locked is already write locked by another process or the type is a write (F_WRLCK) lock and the segment of a file to be locked is already read or write locked by another process. 

[ENOLINK]Fildes is on a remote machine and the link to that machine is no longer active. 

Because in the future the variable errno is set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value. 

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

ULTRIX Compatibility

ERRORS

If the fcntl() function fails, errno may be set to one of the following values:

[EBADF]The filedes or old parameter is not a valid open file descriptor and the argument parameter file descriptor is negative or greater than or equal to the per-process limit. 

[EMFILE]The request parameter is F_DUPFD and too many file descriptors are currently open in the calling process, or no file descriptors greater than or equal to argument are available. 

[EINVAL]The request parameter is F_DUPFD and the argument parameter is negative or greater than or equal to OPEN_MAX. 

[ENOMEM]The system was unable to allocate kernel memory for the requested file descriptor. 

If the dup() or dup2() function fails, errno may be set to one of the following values:

[EMFILE]The number of file descriptors exceeds the per-process limit or there is no file descriptor above the value of the new parameter. 

[ENOMEM]The system was unable to allocate kernel memory for the requested file descriptor. 

RELATED INFORMATION

Functions: getdtablesize(2)
 

RELATED INFORMATION

Functions: close(2), exec(2), lockf(3), open(2), read(2), truncate(2), write(2) creat(2), dup(2), fork(2), pipe(2)