| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- file control
#include <sys/types.h>#include <unistd.h>#include <fcntl.h>intfcntl(intfildes,intcmd,/*arg */ ...);
Thefcntl() function provides for control over open files. Thefildes argumentis an open file descriptor.
Thefcntl() function can take a third argument,arg, whose data type,value, and use depend upon the value ofcmd. Thecmd argumentspecifies the operation to be performed byfcntl().
The values forcmd are defined in <fcntl.h> and include:
Return a new file descriptor which is the lowest numbered available (that is, not already open) file descriptor greater than or equal to the third argument,arg, taken as an integer of typeint. The new file descriptor refers to the same open file description as the original file descriptor, and shares any locks. TheFD_CLOEXEC flag associated with the new file descriptor is cleared to keep the file open across calls to one of theexec(2) functions.
Similar toF_DUPFD, except that theFD_CLOEXEC flag associated with the new file descriptor is set.
Similar toF_DUPFD, except that it always returnsarg.F_DUP2FD closesarg if it is open and not equal tofildes. Iffildes is not equal toarg, theFD_CLOEXEC flag associated with the new file descriptor is cleared. Iffildes is equal toarg, theFD_CLOEXEC flag associated with the new file descriptor is not changed.F_DUP2FD is equivalent todup2(fildes,arg).
Similar toF_DUP2FD, except that theFD_CLOEXEC flag associated with the new file descriptor is set.
Free storage space associated with a section of the ordinary filefildes. The section is specified by a variable of data typestruct flock pointed to byarg. The data typestruct flock is defined in the <fcntl.h> header (seefcntl.h(3HEAD)) and is described below. Note that all file systems might not support all possible variations ofF_FREESP arguments. In particular, many file systems allow space to be freed only at the end of a file.
Equivalent toF_FREESP, but takes astruct flock64 argument rather than astruct flock argument.
Allocate space for a section of the ordinary filefildes. The section is specified by a variable of data typestruct flock pointed to byarg. The data typestruct flock is defined in the <fcntl.h> header (seefcntl.h(3HEAD) and is described below.
Equivalent toF_ALLOCSP, but takes astruct flock64 argument rather than astruct flock argument.
Get the file descriptor flags defined in <fcntl.h> that are associated with the file descriptorfildes. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file.
Get the file status flags and file access modes, defined in <fcntl.h>, for the file descriptor specified byfildes. The file access modes can be extracted from the return value using the maskO_ACCMODE, which is defined in <fcntl.h>. File status flags and file access modes do not affect other file descriptors that refer to the same file with different open file descriptions.
Iffildes refers to a socket, get the process or process group ID specified to receiveSIGURG signals when out-of-band data is available. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. Iffildes does not refer to a socket, the results are unspecified.
Get the file status flags, file access modes, and file creation and assignment flags, defined in <fcntl.h>, for the file descriptor specified byfildes. The file access modes can be extracted from the return value using the maskO_ACCMODE, which is defined in <fcntl.h>. File status flags, file access modes, and file creation and assignment flags do not affect other file descriptors that refer to the same file with different open file descriptions.
Set the file descriptor flags defined in <fcntl.h>, that are associated withfildes, to the third argument,arg, taken as typeint. If theFD_CLOEXEC flag in the third argument is 0, the file will remain open across theexec() functions; otherwise the file will be closed upon successful execution of one of theexec() functions.
Set the file status flags, defined in <fcntl.h>, for the file descriptor specified byfildes from the corresponding bits in thearg argument, taken as typeint. Bits corresponding to the file access mode and file creation and assignment flags that are set inarg are ignored. If any bits inarg other than those mentioned here are changed by the application, the result is unspecified.
Iffildes refers to a socket, set the process or process group ID specified to receiveSIGURG signals when out-of-band data is available, using the value of the third argument,arg, taken as typeint. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. Iffildes does not refer to a socket, the results are unspecified.
The following commands are available for advisory record locking. Record locking issupported for regular files, and may be supported for other files.
Get the first lock which blocks the lock description pointed to by the third argument,arg, taken as a pointer to typestruct flock, defined in<fcntl.h>. The information retrieved overwrites the information passed tofcntl() in the structureflock. If no lock is found that would prevent this lock from being created, then the structure will be left unchanged except for the lock type which will be set toF_UNLCK.
Equivalent toF_GETLK, but takes astruct flock64 argument rather than astruct flock argument.
Set or clear a file segment lock according to the lock description pointed to by the third argument,arg, taken as a pointer to typestruct flock, defined in <fcntl.h>.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 andF_UNLCK are defined in <fcntl.h>. If a shared or exclusive lock cannot be set,fcntl() will return immediately with a return value of-1.
Equivalent toF_SETLK, but takes astruct flock64 argument rather than astruct flock argument.
This command is the same asF_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 whilefcntl() is waiting for a region,fcntl() will be interrupted. Upon return from the process' signal handler,fcntl() will return-1 witherrno set toEINTR, and the lock operation will not be done.
Equivalent toF_SETLKW, but takes astruct flock64 argument rather than astruct flock argument.
When a shared lock is set on a segment of a file,other processes will be able to set shared locks on that segmentor a portion of it. A shared lock prevents any other processfrom setting an exclusive lock on any portion of the protected area.A request for a shared lock will fail if the file descriptor wasnot opened with read access.
An exclusive lock will prevent any other process from setting a sharedlock or an exclusive lock on any portion of the protected area.A request for an exclusive lock will fail if the file descriptorwas not opened with write access.
Theflock structure contains at least the following elements:
short l_type; /* lock operation type */ short l_whence; /* lock base indicator */ off_t l_start; /* starting offset from base */ off_t l_len; /* lock length; l_len == 0 means until end of file */ int l_sysid; /* system ID running process holding lock */ pid_t l_pid; /* process ID of process holding lock */
The value ofl_whence isSEEK_SET,SEEK_CUR, orSEEK_END, to indicate thatthe relative offsetl_start bytes will be measured from the start ofthe file, current position or end of the file, respectively. The value ofl_len is the number of consecutive bytes to be locked. The valueofl_len may be negative (where the definition ofoff_t permits negativevalues ofl_len). After a successfulF_GETLK orF_GETLK64 request, that is,one in which a lock was found, the value ofl_whence willbeSEEK_SET.
Thel_pid andl_sysid fields are used only withF_GETLK orF_GETLK64to return the process ID of the process holding a blocking lockand to indicate which system is running that process.
Ifl_len is positive, the area affected starts atl_start and endsatl_start +l_len - 1. Ifl_len is negative, the area affected startsatl_start +l_len and ends atl_start - 1. Locks may start and extendbeyond the current end of a file, but must not be negativerelative to the beginning of the file. A lock will be setto extend to the largest possible value of the file offset forthat file by settingl_len to 0. If such a lock also hasl_start set to 0 andl_whence is set toSEEK_SET, the wholefile will be locked.
If a process has an existing lock in whichl_len is 0and which includes the last byte of the requested segment, and anunlock (F_UNLCK) request is made in whichl_len is non-zero and theoffset of the last byte of the requested segment is the maximum valuefor an object of typeoff_t, then theF_UNLCK request will betreated as a request to unlock from the start of the requestedsegment with anl_len equal to 0. Otherwise, the request will attemptto unlock only the requested segment.
There will be at most one type of lock set for eachbyte in the file. Before a successful return from anF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64 request when the calling process has previously existing locks onbytes in the region specified by the request, the previous lock typefor each byte in the specified region will be replaced by thenew lock type. As specified above under the descriptions of shared locksand exclusive locks, anF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64 request will (respectively)fail or block when another process has existing locks on bytes inthe specified region and the type of any of those locks conflictswith the type specified in the request.
All locks associated with a file for a given process are removedwhen a file descriptor for that file is closed by that processor the process holding that file descriptor terminates. Locks are not inheritedby a child process created usingfork(2).
A potential for deadlock occurs if a process controlling a locked regionis put to sleep by attempting to lock another process' locked region.If the system detects that sleeping until a locked region is unlockedwould cause a deadlock,fcntl() will fail with anEDEADLK error.
The following values forcmd are used for file share reservations. Ashare reservation is placed on an entire file to allow cooperating processesto control access to the file.
Sets a share reservation on a file with the specified access mode and designates which types of access to deny.
Remove an existing share reservation.
File share reservations are an advisory form of access control among cooperatingprocesses, on both local and remote machines. They are most often usedby DOS or Windows emulators and DOS based NFS clients. However, native UNIXversions of DOS or Windows applications may also choose to use this formof access control.
A share reservation is described by anfshare structure defined in <sys/fcntl.h>,which is included in <fcntl.h> as follows:
typedef struct fshare { short f_access; short f_deny; int f_id;} fshare_t;A share reservation specifies the type of access,f_access, to be requestedon the open file descriptor. If access is granted, it further specifieswhat type of access to deny other processes,f_deny. A single processon the same file may hold multiple non-conflicting reservations by specifying anidentifier,f_id, unique to the process, with each request.
AnF_UNSHARE request releases the reservation with the specifiedf_id. Thef_accessandf_deny fields are ignored.
Validf_access values are:
Set a file share reservation for read-only access.
Set a file share reservation for write-only access.
Set a file share reservation for read and write access.
Validf_deny values are:
Set a file share reservation to compatibility mode.
Set a file share reservation to deny read access to other processes.
Set a file share reservation to deny write access to other processes.
Set a file share reservation to deny read and write access to other processes.
Do not deny read or write access to any other process.
Upon successful completion, the value returned depends oncmd as follows:
A new file descriptor.
A new file descriptor.
A new file descriptor.
A new file descriptor.
Value of0.
Value of flags defined in<fcntl.h>. The return value will not be negative.
Value of file status flags and access modes. The return value will not be negative.
Value other than-1.
Value other than-1.
Value of the socket owner process or process group; this will not be-1.
Value of file status flags, access modes, and creation and assignment flags. The return value will not be negative.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Value other than-1.
Otherwise,-1 is returned anderrno is set to indicate the error.
Thefcntl() function will fail if:
Thecmd argument isF_SETLK orF_SETLK64, 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; or 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.
Thecmd argument isF_FREESP, the file exists, mandatory file/record locking is set, and there are outstanding record locks on the file; or thecmd argument isF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64, mandatory file/record locking is set, and the file is currently being mapped to virtual memory usingmmap(2).
Thecmd argument isF_SHARE andf_access conflicts with an existingf_deny share reservation.
Thefildes argument is not a valid open file descriptor; or thecmd argument isF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64, the type of lock,l_type, is a shared lock (F_RDLCK), andfildes is not a valid file descriptor open for reading; or the type of lockl_type is an exclusive lock (F_WRLCK) andfildes is not a valid file descriptor open for writing.
Thecmd argument isF_FREESP andfildes is not a valid file descriptor open for writing.
Thecmd argument isF_DUP2FD orF_DUP2FD_CLOEXEC andarg is negative or is not less than the current resource limit forRLIMIT_NOFILE.
Thecmd argument isF_SHARE, thef_access share reservation is for write access, andfildes is not a valid file descriptor open for writing.
Thecmd argument isF_SHARE, thef_access share reservation is for read access, andfildes is not a valid file descriptor open for reading.
Thecmd argument isF_GETLK,F_GETLK64,F_SETLK,F_SETLK64,F_SETLKW,F_SETLKW64, orF_FREESP and thearg argument points to an illegal address.
Thecmd argument isF_SHARE orF_UNSHARE andarg points to an illegal address.
Thecmd argument isF_SETLKW orF_SETLKW64 and the function was interrupted by a signal.
Thecmd argument is invalid or not supported by the file system; or thecmd argument isF_DUPFD orF_DUPFD_CLOEXEC andarg is negative or greater than or equal toOPEN_MAX; or thecmd argument isF_GETLK,F_GETLK64,F_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64 and the data pointed to byarg is not valid; orfildes refers to a file that does not support locking.
Thecmd argument isF_UNSHARE and a reservation with thisf_id for this process does not exist.
An I/O error occurred while reading from or writing to the file system.
Thecmd argument isF_DUPFD orF_DUPFD_CLOEXEC and eitherOPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal toarg are available.
Thecmd argument isF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64 and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit.
Either thefildes argument is on a remote machine and the link to that machine is no longer active; or thecmd argument isF_FREESP, the file is on a remote machine, and the link to that machine is no longer active.
One of the values to be returned cannot be represented correctly.
Thecmd argument isF_GETLK,F_SETLK, orF_SETLKW and the smallest or, ifl_len is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of typeoff_t.
Thecmd argument isF_GETLK64,F_SETLK64, orF_SETLKW64 and the smallest or, ifl_len is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of typeoff64_t.
Thefcntl() function may fail if:
Thecmd argument isF_SETLK,F_SETLK64,F_SETLKW, orF_SETLKW64, and the file is currently being mapped to virtual memory usingmmap(2).
Thecmd argument isF_SETLKW orF_SETLKW64, the lock is blocked by some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a deadlock.
Thecmd argument isF_FREESP, mandatory record locking is enabled,O_NDELAY andO_NONBLOCK are clear and a deadlock condition was detected.
Seeattributes(5) for descriptions of the following attributes:
|
lockd(1M),chmod(2),close(2),creat(2),dup(2),exec(2),fork(2),mmap(2),open(2),pipe(2),read(2),sigaction(2),write(2),dup2(3C),fcntl.h(3HEAD),attributes(5),standards(5)
In the past, the variableerrno was set toEACCES rather thanEAGAIN when a section of a file is already locked by anotherprocess. Therefore, portable application programs should expect and test for either value.
Advisory locks allow cooperating processes to perform consistent operations on files, butdo not guarantee exclusive access. Files can be accessed without advisory locks,but inconsistencies may result. The network share locking protocol does not supportthef_deny value ofF_COMPAT. For network file systems, iff_access isF_RDACC,f_deny is mapped toF_RDDNY. Otherwise, it is mapped toF_RWDNY.
To prevent possible file corruption, the system may rejectmmap() requests foradvisory locked files, or it may reject advisory locking requests for mappedfiles. Applications that require a file be both locked and mapped shouldlock the entire file (l_start andl_len both set to 0). Ifa file is mapped, the system may reject an unlock request, resultingin a lock that does not cover the entire file.
The process ID returned for locked files on network file systems mightnot be meaningful.
If the file server crashes and has to be rebooted, the lockmanager (seelockd(1M)) attempts to recover all locks that were associated withthat server. If a lock cannot be reclaimed, the process that held thelock is issued aSIGLOST signal.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |