HP 3000 Manuals HP 3000 Manuals
fcntl
File control.
Syntax
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
int fcntl(int *fildes, int cmd, ...);
Parameters
fildes An open file descriptor.
cmd The following values can be used for the file control command.
F_DUPFD Duplicate file descriptor.
F_GETFD Get file descriptor flags.
F_GETLK Get record locking information.
F_SETFD Set file descriptor flags.
F_GETFL Get file status flags.
F_SETFL Set file status flags.
F_SETLK Set record locking information.
F_SETLKW Set record locking information;wait if
blocked.
FD_CLOEXEC Close file descriptor upon execution of an
exec-family function.
l_type Values for Record Locking With fcntl()
F_RDLCK Shared or read lock.
F_UNLCK Unlock.
F_WRLCK Exclusive or write lock.
oflag Values for open()
O_CREAT Create file if it does not exist.
O_EXCL Exclusive use flag.
O_NOCITY Do not assign a controlling terminal.
O_TRUNC Truncate flag.
File Status Flags Used for open() and fcntl()
O_APPEND Set append mode.
O_NONBLOCK No delay.
File Access Modes Used for open() and fcntl()
O_RDONLY Open for reading only.
O_RDWR Open for reading and writing.
O_WRONLY Open for writing only.
Mask for Use With File Access Modes
O_ACCMODE Mask for file access modes.
Return Values
>=0 Success. A nonnegative integer is returned representing the
lowest numbered file descriptor not open by the calling
process.
-1 An error occurred. The file is not opened, and errno is set
to indicate the error condition.
Description
Upon successful completion, the value returned will depend on cmd. The
various return values are shown in Table 6-9.
Otherwise, a value of -1 will be returned and errno will be set to
indicate the error.
The available values for cmd are defined in the <fcntl.h> (see 6.5.1)
which will include:
F_DUPFD Return a new file descriptor that is the lowest numbered
avaliable file descriptor greater than or equal to the
third argument, arg, taken as an integer of type int. The
new file descriptor refers to the same open file
description as the original file descriptor and shares any
locks.
The FD_CLOEXEC flag associated with the new file descriptor
cleared to keep the file open across calls to the exec
family of functions.
F_GETFD Get the file descriptor flags that are associated with the
file descriptor fildes. File descriptor flags are
associated with a single file descriptor and do not affect
other file descriptors that refer to the same file.
F_GETLK
F_SETFD Set the file descriptor flags that are associated with
fildes to the third argument, arg taken as type int. If
the FD_CLOEXEC flag is zero, the file will be closed upon
successful execution of an exec function.
F_GETFL Get the file status flags and the file access modes for the
open file description associated with fildes. The file
access modes can be extracted from the return value using
the mask O_ACCMODE, which is defined in <fcntl.h>. File
status flags and file access modes are associated with the
open file description and do not affect other file
descriptors that refer to the same file with different open
file descriptions.
F_SETFL Set the file status flags for the open file description
associated with fildes from the corresponding bits in the
third argument, arg, taken as type int. Bits corresponding
to the file access modes and the oflag values that are set
in arg are ignored. If any bits in arg other than those
mentioned here are changed by the application, the result
is unspecified.
The following commands are available for advisory record locking.
Advisory record locking shall be supported for regular files, and may be
supported for other files.
F_GETLK Get the first lock that blocks the lock description pointed
to by the third argument, arg, taken as a pointer to type
struct flock (see below) The information retrived
overwrites the information passed to fcntl() in the flock
structure. If no lock is found that would prevent this
lock from being created, the structure will be left
unchanged by this function call except for the lock type,
which will be set to F_UNLCK.
F_SETLK Set or clear a file segment lock according to the lock
description pointed to by the third argument, arg, taken as
a pointer to type struct flock (see below). F_SETLK is
used to establish shared (or read) locks (F_RDLCK) or
exclusive (or write) locks, (F_WRLCK), as well as to remove
either type of lock (F_UNLCK). F_RDLCK, F_WRLCK, and
F_UNLCK are defined by the <fcntl.h> header. If shared or
exclusive lock cannot be set, fcntl() will return
immediately.
F_SETLKW This command is the same as F_SETLK except that if a shared
or exclusive lock is blocked by other locks, the process
will wait until the request can be satisfied. If a signal
that is to be caught is received while fcntl will be
interrupted. Upon return from the signal handler of the
process, fcntl() will return -1 with errno set to [EINTR],
and the lock operation will not be done.
The flock structure, defined by the <fcntl.h> header, describes an
advisory lock. It includes the members shown in Table 6-8.
When a shared lock has been set on a segment of a file, other processes
will be 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 will fail
if the file descriptor was not opened with read access.
An exclusive lock will prevent 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 will fail if the file descriptor was not
opened with write access.
The value of l_whence is DEEK_SET, SEEK_CUR, or SEEK_END to indicate that
the relative offset, L_START bytes, will be measured from the start of
the file, current position, or end of the file, respectively, The value
of l_en is the number of consecutive bytes to be locked. If l_len is
negative, the result is undefined. The l_pid field is only used with
F_GETLK to return the process ID of the process holeing a blocking lock.
After a successful F_GETLK request, the value of l_whence will be
SEEK_SET.
flock Structure
Member Type Member Name Description
short l_type F_RDLCK,F_WRLCK,or F_UNLCK.
short l_whence Flag for starting offset.
off_t l_start Relative offset in bytes.
off_t l_len Size;if 0,then until EOF.
pid_t l_pid Process ID of the process holding
the lock, returned with F_GETLK.
Locks may start and extend beyond the current end of a file, but, will
not start or extend before the beginning of the file. A lock will be set
to extend to the largest possible value of the file offset for that file
is l_len is set to zero. If the flock struct has l_whence and l_start
that point to the beginning of the file, and l_len of zero, the intire
file will be locked.
There will be at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK or an F_SETLKW request when
the calling process has previously existing locks on bytes in the region
specified by the request, the previous lock type for each byte in the
specified region will be replaced by the new lock type. As specified
above under the descriptions of shared locks and exclusive locks, and
F_SETLK of an F_SETLKW request will (respectively) fail or block when
another process has existing locks on bytes in the specified region and
the type of any of those locks conflicts with the type specified in the
request.
All locks associated with a file for a given process will be 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 created useing the fork() function.
A potential for deadlock occurs if a process controlling a locked region
is put to sleep by attempting to lock the locked region of another
process. If the system detects that sleeping until a locked region is
unlocked would cause a deadlock, the fcntl() function will fail with an
[EDEADLK]error.
Description
The function fcntl() provides for control over open files. The argument
fildes is a file descriptor.
Implementation Considerations
The calling process must have the correct access permissions as defined
by either an attached ACD or by the MPE/iX file security matrix. For
example, a file opened O_RDONLY must have either ACD read access or
MPE/iX read access. A file opened O_WRONLY or O_RDWR must have either
ACD write access and append access or MPE/iX write access and append
access.
Errors
If an error occurs, errno is set to one of the following values:
EACCES CAUSE One of the following:
* The calling process does not have search
permission to a component of the pathname.
* The file does not exist and the calling
process does not have write permission to the
parent directory of the file to be created.
* The file exists and the permissions specified
by oflag are denied.
* Both O_TRUNC and O_RDONLY were specified.
* Both O_APPEND and O_RDONLY were specified.
* An MPE/iX lockword is associated with the
file.
ACTION One of the following:
* Make sure that the calling process has search
permission to all directory components of the
pathname.
* Make sure that the calling process has write
permission to the parent directory of the file
to be created.
* Specify valid and compatible flags in oflag.
* Remove the MPE/iX lockword.
Table 4-0. (cont.)
EBADF CAUSE The fildes argument is not a valid file descriptor.
The argument cmd is F_SETLK or F_SETLKW, the type of
lock (l_type) is shared lock(F_RDLCK), and fildes is
not a valid file descriptor open for reading.
The argument cmd is F_SETLK or F_SETLKW, the type of
lock (l_type) is an exclusive lock(F_WLRCK), and
fildes is not a valid file descriptor open for
writing.
ACTION None.
EINTR CAUSE The argument cmd is F_SETLKW, and the function was
interrupted by a signal.
ACTION None.
EINVAL CAUSE More than one of the following three open flags were
specified in oflag: O_WRONLY, O_RDONLY, and O_RDWR.
ACTION Specify only one of the open flags in oflag.
EMFILE CAUSE The argument cmd if F_DUPED and {OPEN_MAX} file
descriptors are currently in use by this process, or
no file descriptors greater than or equal to arg are
available.
ACTION None.
ENOLCK CAUSE The argument cmd 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.
ACTION None.
For each of the following conditions, if the condition is detected, the
fcntl() function will return -1 and set errno to the corresponding value:
EDEADLK CAUSE The argument cmd is F_SETLKW, and a deadlock
condition was detected.
ACTION None.
EAGAIN CAUSE The system lacked the resources to create another
process.
ACTION Attempt process creation at a later time, or decrease
the number of processes associated with the
application.
EPERM CAUSE One of the following:
* The calling process does not have the MPE/iX
process handling (PH) capability.
* The calling process has outstanding switches
to CM code, has set critical mode, has
outstanding NOWAITIO, or is holding an
operating system internal resource.
ACTION One of the following:
* Link the program file with the MPE/iX PH
capability.
* Do not execute execl() when the calling
process has outstanding switches to CM code,
has set critical mode, has outstanding
NOWAITIO, or is holding an operating system
internal resource.
See Also
close(), exec(), open(), <fcntl.h>, (POSIX.1).