gtpc2m26 | C/C++ Language Support User's Guide |
This function controls the open file descriptors.
Format
#include <fcntl.h> int fcntl(int fildes, int action, ...);
The action argument can be one of the following symbols:
TPF deviation from POSIX |
---|
The TPF system does not support the F_GETLK and F_SETLK action parameter values. |
Performs various actions on open file descriptors.
There are several types of flags associated with each open file. Flags for a file are represented by symbols defined in the fcntl.h header file.
The following file descriptor flag can be associated with a file:
The following file status flags can be associated with a file:
The following file access mode flags can be associated with a file:
Two masks can be used to extract flags:
The following TPF-specific control flag can be associated with a file:
TPF deviation from POSIX |
---|
The only file locking supported by the TPF system is a blocking exclusive lock over an entire file. The fcntl function options to lock a range of bytes in a file (other than the entire file), to attempt to lock without blocking, to get a shared lock, and to query locks are not supported. |
A process can use the fcntl function to lock out other processes from a file so that the process can read or write to that part of the file without interference from other files. File locking can ensure data integrity when several processes have a file accessed concurrently. File locking can be performed only on file descriptors that refer to regular files. Locking is not permitted on file descriptors that refer to directories, character special files, or any other type of files.
A structure that has the type struct flock (defined in the fcntl.h header file) controls locking operations. This structure has the following members:
TPF deviation from POSIX |
---|
To allow a reader to get exclusive access to a file, the requirement to have write access to the file when requesting a write lock is not enforced. |
TPF deviation from POSIX |
---|
The TPF system does not support read or shared locks. The fcntl function does not accept the F_RDLCK lock type. |
This symbol is defined in the unistd.h header file and is the same as used by the lseek function.
TPF deviation from POSIX |
---|
The TPF system does not accept the SEEK_CUR and SEEK_END values for this field. |
TPF deviation from POSIX |
---|
The TPF system does not support the pid_t l_pid field of the flock structure. |
You can set a lock by specifying F_SETLKW as the action argument for the fcntl function. Such a function call requires a third argument pointing to a struct flock structure as in the following example:
struct flock lock_it; lock_it.l_type = F_WRLCK; lock_it.l_whence = SEEK_SET; lock_it.l_start = 0; lock_it.l_len = 0; fcntl(fildes, F_SETLKW, &lock_it);
The previous example requests an exclusive lock for the entire file, which is the only type of lock that the TPF system supports. You can unlock this lock by setting l_type to F_UNLCK and making the same call. If an F_SETLKW operation cannot set a lock, it waits until the lock can be set. For example, if you want to establish a lock and some other process already has a lock established on the same file, fcntl waits until the other process has removed its lock.
Deadlocks can occur with F_SETLKW operations when process A is waiting for process B to unlock a file, and process B is waiting for process A to unlock a different file. Applications that lock more than one file at a time need to establish locking conventions that prevent more than one process from deadlocking.
A process lock on a file is removed when the process closes any file descriptor that refers to the locked file. Locks are not inherited by child processes created with system.
All locks are advisory only. Processes can use locks to inform each other that they want to protect a file, but locks do not prevent I/O on the locked files. If a process has appropriate permissions on a file, it can perform whatever I/O it chooses regardless of what locks are set. Therefore, file locking is only a convention, and it works only when all processes respect the convention.
Normal Return
If successful, the value returned will depend on the action that was specified.
Error Return
If unsuccessful, fcntl returns -1 and sets errno to one of the following:
In a locking operation, fildes refers to a file with a type that does not support locking, or the struct flock pointed to by the third argument has an incorrect form.
Programming Considerations
None.
Examples
The following example opens a file and requests an exclusive lock for the entire file.
#include <fcntl.h> #include <stdio.h> int main(void) { int fd = open("my.file", O_RDWR); if (fd < 0) { perror("open failure"); } else { struct flock lock_it; lock_it.l_type = F_WRLCK; lock_it.l_whence = SEEK_SET; lock_it.l_start = 0; lock_it.l_len = 0; fcntl(fd, F_SETLKW, &lock_it);
·
·
·
close(fd) /* close releases the lock */ } }
Related Information
See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.