fcntl()--Perform File Control Command

 #include <sys/types.h>
 #include <unistd.h>
 #include <fcntl.h>

 int fcntl(int descriptor,
          int command,
          ...)  

The fcntl() function performs various actions on open descriptors, such as obtaining or changing the attributes of a file or socket descriptor.

Parameters

descriptor

(Input)  The descriptor on which the control command is to be performed, such as having its attributes retrieved or changed.

command

(Input)  The command that is to be performed on the descriptor.

...

(Input) A variable number of optional parameters that is dependent on the command. Only some of the commands use this parameter.

The fcntl() commands that are supported are:

F_DUPFD	Duplicates the descriptor. A third int argument must be specified. fcntl() returns the lowest descriptor greater than or equal to this third argument that is not already associated with an open file. This descriptor refers to the same object as descriptor and shares any locks. If the original descriptor was opened in text mode, data conversion is also done on the duplicated descriptor. The FD_CLOEXEC flag that is associated with the new descriptor is cleared.
F_GETFD	Obtains the descriptor flags for descriptor. fcntl() returns these flags as its result. For a list of supported file descriptor flags, see Flags. Descriptor flags are associated with a single descriptor and do not affect other descriptors that refer to the same object.
F_GETFL	Obtains the open flags for descriptor. fcntl() returns these flags as its result. For a list of the open flags, see Using the oflag Parameter in open().
F_GETLK	Obtains locking information for an object. You must specify a third argument of type struct flock *. See File Locking for details. fcntl() returns 0 if it successfully obtains the locking information. When you develop in C-based languages and the function is compiled with the _LARGE_FILES macro defined, F_GETLK is mapped to the F_GETLK64 symbol.
F_GETLK64	Obtains locking information for a large file. You must specify a third argument of type struct flock64 *. See File Locking for details. fcntl() returns 0 if it successfully obtains the locking information. When you develop in C-based languages, it is necessary to compile the function with the _LARGE_FILE_API macro defined to use this symbol.
F_GETOWN	Returns the process ID or process group ID that is set to receive the SIGIO (I/O is possible on a descriptor) and SIGURG (urgent condition is present) signals. For more information, see Signal APIs.
F_SETFD	Sets the descriptor flags for descriptor. You must specify a third int argument, which gives the new file descriptor flag settings (see Flags). If any other bits in the third argument are set, fcntl() fails with the [EINVAL] error. fcntl() returns 0 if it successfully sets the flags. Descriptor flags are associated with a single descriptor and do not affect other descriptors that refer to the same object.
F_SETFL	Sets status flags for the descriptor. You must specify a third int argument, giving the new file status flag settings (see Flags). fcntl() does not change the file access mode, and file access bits in the third argument are ignored. All other oflag values that are valid on the open() API are also ignored. If any other bits in the third argument are set, fcntl() fails with the [EINVAL] error. fcntl() returns 0 if it successfully sets the flags.
F_SETLK	Sets or clears a file segment lock. You must specify a third argument of type struct flock *. See File Locking for details. fcntl() returns 0 if it successfully clears the lock. When you develop in C-based languages and the function is compiled with the _LARGE_FILES macro defined, F_SETLK is mapped to the F_SETLK64 symbol.
F_SETLK64	Sets or clears a file segment lock for a large file. You must specify a third argument of type struct flock64 *. See File Locking for details. fcntl() returns 0 if it successfully clears the lock. When you develop in C-based languages, it is necessary to compile the function with the _LARGE_FILE_API macro defined to use this symbol.
F_SETLKW	Sets or clears a file segment lock; however, if a shared or exclusive lock is blocked by other locks, fcntl() waits until the request can be satisfied. You must specify a third argument of type struct flock *. See File Locking for details. When you develop in C-based languages and the function is compiled with the _LARGE_FILES macro defined, F_SETLKW is mapped to the F_SETLKW64 symbol.
F_SETLKW64	Sets or clears a file segment lock on a large file; however, if a shared or exclusive lock is blocked by other locks, fcntl() waits until the request can be satisfied. See File Locking for details. You must specify a third argument of type struct flock64 *. When you develop in C-based languages, it is necessary to compile the function with the _LARGE_FILE_API macro defined to use this symbol.
F_SETOWN	Sets the process ID or process group ID that is to receive the SIGIO and SIGURG signals. For more information, see Signal APIs.

Flags

There are several types of flags associated with each open object. Flags for an object are represented by symbols defined in the <fcntl.h header file. The following file status flags can be associated with an object:

FASYNC	The SIGIO signal is sent to the process when it is possible to do I/O. This function will fail with error code [EINVAL] when fildes is for an object other than a socket.
FNDELAY	This flag is defined to be equivalent to O_NDELAY.
O_APPEND	Append mode. If this flag is 1, every write operation on the file begins at the end of the file.
O_DSYNC	Synchronous update - data only. If this flag is 1, all file data is written to permanent storage before the update operation returns. Update operations include, but are not limited to, the following: ftruncate(), open() with O_TRUNC, and write().
O_NDELAY	This flag is defined to be equivalent to O_NONBLOCK.
O_NONBLOCK	Non-blocking mode. If this flag is 1, read or write operations on the file will not cause the thread to block. This file status flag applies only to pipe, FIFO, and socket descriptors.
O_RSYNC	Synchronous read. If this flag is 1, read operations to the file will be performed synchronously. This flag is used in combination with O_SYNC or O_DSYNC. When O_RSYNC and O_SYNC are set, all file data and file attributes are written to permanent storage before the read operation returns. When O_RSYNC and O_DSYNC are set, all file data is written to permanent storage before the read operation returns.
O_SYNC	Synchronous update. If this flag is 1, all file data and file attributes relative to the I/O operation are written to permanent storage before the update operation returns. Update operations include, but are not limited to, the following: ftruncate(), open() with O_TRUNC, and write().

The following file access mode flags can be associated with a file:

A mask can be used to extract flags:

The following descriptor flags can be associated with a descriptor:

Refer to spawn()--Spawn Process and spawnp()--Spawn Process with Path for additional information about FD_CLOEXEC.

File Locking

A local or remote job can use fcntl() to lock out other local or remote jobs from a part of a file. By locking out other jobs, the job can read or write to that part of the file without interference from others. File locking can ensure data integrity when several jobs have a file accessed concurrently. For more information about remote locking, see information about the network lock manager and the network status monitor in the Network File System Support book.

All locks obtained using fcntl() are advisory only. Jobs can use advisory locks to inform each other that they want to protect parts of a file, but advisory locks do not prevent input and output on the locked parts. If a job has appropriate permissions on a file, it can perform whatever I/O it chooses, regardless of what advisory locks are set. Therefore, advisory locking is only a convention, and it works only when all jobs respect the convention.

Another type of lock, called a mandatory lock, can be set by a remote personal computer application. Mandatory locks restrict I/O on the locked parts. A read fails when reading a part that is locked with a mandatory write lock. A write fails when writing a part that is locked with a mandatory read or mandatory write lock.

Two different structures are used to control locking operations: struct flock and struct flock64 (both defined in the <fcntl.h header file). You can use struct flock64 with the F_GETLK64, F_SETLK64, and F_SETLKW64 commands to control locks on large files (files greater than 2GB minus 1 byte). The struct flock structure has the following members:

When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, the struct flock data type will be mapped to a struct flock64 data type. To use the struct flock64 data type explicitly, it is necessary to compile the function with _LARGE_FILE_API defined.

The struct flock64 structure has the following members:

You can set locks by specifying F_SETLK or F_SETLK64 as the command argument for fcntl(). Such a function call requires a third argument pointing to a struct flock structure (or struct flock64 in the case of F_SETLK64), as in this example:

   struct flock lock_it;
   lock_it.l_type = F_RDLCK;
   lock_it.l_whence = SEEK_SET;
   lock_it.l_start = 0;
   lock_it.l_len = 100;
   fcntl(file_descriptor,F_SETLK,&lock_it);

This example sets up a flock structure describing a read lock on the first 100 bytes of a file, and then calls fcntl() to establish the lock. You can unlock this lock by setting l_type to F_UNLCK and making the same call. If an F_SETLK operation cannot set a lock, it returns immediately with an error saying that the lock cannot be set.

The F_SETLKW and F_SETLKW64 operations are similar to F_SETLK and F_SETLK64, except that they wait until the lock can be set. For example, if you want to establish an exclusive lock and some other job already has a lock established on an overlapping part of the file, fcntl() waits until the other process has removed its lock.

F_SETLKW and F_SETLKW64 operations can encounter deadlocks when job A is waiting for job B to unlock a region and job B is waiting for job A to unlock a different region. If the system detects that an F_SETLKW or F_SETLKW64 might cause a deadlock, fcntl() fails with errno set to [EDEADLK].

With the F_SETLK64, F_SETLKW64, and F_GETLK64 operations, the maximum offset that can be specified is the largest value that can be held in an 8-byte, signed integer.

A job can determine locking information about a file by using F_GETLK and F_GETLK64 as the command argument for fcntl(). In this case, the call to fcntl() should specify a third argument pointing to a flock structure. The structure should describe the lock operation you want. When fcntl() returns, the structure indicated by the flock pointer is changed to show the first lock that would prevent the proposed lock operation from taking place. The returned structure shows the type of lock that is set, the part of the file that is locked, and the job ID of the job that holds the lock. In the returned structure:

• l_whence is always SEEK_SET.
• l_start gives the offset of the locked portion from the beginning of the file.
• l_len is the length of the locked portion.

If there are no locks that prevent the proposed lock operation, the returned structure has F_UNLCK in l_type and is otherwise unchanged.

If fcntl() attempts to operate on a large file (one larger than 2GB minus 1 byte) with the F_SETLK, F_GETLK, or FSETLKW commands, the API fails with [EOVERFLOW]. To work with large files, compile with the _LARGE_FILE_API macro defined (when you develop in C-based languages) and use the F_SETLK64, F_GETLK64, or FSETLKW64 commands. When you develop in C-based languages, it is also possible to work with large files by compiling the source with the _LARGE_FILES macro label defined. Note that the file must have been opened for large file access (either the open64() API was used or the open() API was used with the O_LARGEFILE flag defined in the oflag parameter).

An application that uses the F_SETLK or F_SETLKW commands may try to lock or unlock a file that has been extended beyond 2GB minus 1 byte by another application. If the value of l_len is set to 0 on the lock or unlock request, the byte range held or released will go to the end of the file rather than ending at offset 2GB minus 2.

An application that uses the F_SETLK or F_SETLKW commands also may try to lock or unlock a file that has been extended beyond offset 2GB minus 2 with l_len NOT set to 0. If this application attempts to lock or unlock the byte range up to offset 2GB minus 2 and l_len is not 0, the unlock request will unlock the file only up to offset 2GB minus 2 rather than to the end of the file.

A job can have several locks on a file at the same time, but only one type of lock can be set on a given byte. Therefore, if a job puts a new lock on a part of a file that it had locked previously, the job has only one lock on that part of the file. The type of the lock is the one specified in the most recent locking operation.

Locks can start and extend beyond the current end of a file, but cannot start or extend ahead of the beginning of a file.

All of the locks a job has on a file are removed when the job closes any descriptor that refers to the locked file.

The maximum starting offset that can be specified by using the fnctl() API is 2⁶³ - 1, the largest number that can be represented by a signed 8-byte integer. Mandatory locks set by a personal computer application or by a user of the DosSetFileLocks64() API may lock a byte range that is greater than 2⁶³ - 1.

An application that uses the F_SETLK64 or F_SETLKW64 commands can lock the offset range that is beyond 2⁶³ - 1 by locking offset 2⁶³ - 1. When offset 2⁶³ - 1 is locked, it implicitly locks to the end of the file. The end of the file is the largest number than can be represented by an 8-byte unsigned integer or 2⁶⁴ - 1. This implicit lock may inhibit the personal computer application from setting mandatory locks in the range not explicitly accessable by the fcntl() API.

Any lock set using the fcntl() API that locks offset 2⁶³ - 1 will have a length of 0.

An application that uses the F_GETLK64 may encounter a mandatory lock set by a personal computer application, which locks a range of offsets greater than 2⁶³ - 1. This lock conflict will have a starting offset equal to or less than 2⁶³ - 1 and a length of 0.

Authorities

No authorization is required.

Return Value

Error Conditions

If fcntl() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could also indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
     
     
2. If F_DUPFD is specified as the fcntl() command, this function will fail with error code [EBADF] when fildes is a scan descriptor that was passed to one of the scan-related exit programs. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
   
3. If the fcntl() command is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ENOTSUP] if F_SETLK, F_SETLK64, F_SETLKW or F_SETLKW64 is specified. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
4. QSYS.LIB and Independent ASP QSYS.LIB File System Differences
   
   

   The following fcntl() commands are not supported:

   • F_GETLK
   • F_SETLK
   • F_SETLKW

   Using any of these commands results in an [ENOSYS] error.

5. Network File System Differences
   
   

   Reading and writing to a file with the Network File System relies on byte-range locking to guarantee data integrity. To prevent data inconsistency, use the fcntl() API to get and release these locks. For more information about remote locking, see information about the network lock manager and the network status monitor in the Network File System Support book.

6. QNetWare File System Differences
   
   

   F_GETLK and F_SETLKW are not supported. F_RDLCK and F_WRLCK are ignored. All locks prevent reading and writing. Advisory locks are not supported. All locks are mandatory locks. Locking a file that is opened more than once in the same job with the same access mode is not supported, and its result is undefined.

7. This function will fail with the [EOVERFLOW] error if the command is F_GETLK, F_SETLK, or F_SETLKW and the offset or the length exceeds offset 2 GB minus 2.
   
   
8. When you develop in C-based languages and an application is compiled with the _LARGE_FILES macro defined, the struct flock data type will be mapped to a struct flock64 data type. To use the struct flock64 data type explicitly, it is necessary to compile the function with the _LARGE_FILE_API defined.
   
   
9. In several cases, similar function can be obtained by using ioctl().

Related Information

• The <sys/types.h> file (see Header Files for UNIX-Type Functions)
• The <unistd.h> file (see Header Files for UNIX-Type Functions)
• The <fcntl.h> file (see Header Files for UNIX-Type Functions)
• close()--Close File or Socket Descriptor
• dup()--Duplicate Open File Descriptor
• dup2()--Duplicate Open File Descriptor to Another Descriptor
• ioctl()--Perform I/O Control Request
• lseek()--Set File Read/Write Offset
• open()--Open File
• spawn()--Spawn Process
• spawnp()--Spawn Process with Path
• Network File System Support book

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses fcntl():

#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>

int main()
{
  int flags;
  int append_flag;
  int nonblock_flag;
  int access_mode;
  int file_descriptor; /* File Descriptor */
  char *text1 = "abcdefghij";
  char *text2 = "0123456789";
  char read_buffer[25];

  memset(read_buffer, '\0', 25);

  /* create a new file */
  file_descriptor = creat("testfile",S_IRWXU);
  write(file_descriptor, text1, 10);
  close(file_descriptor);

  /* open the file with read/write access */
  file_descriptor = open("testfile", O_RDWR);
  read(file_descriptor, read_buffer,24);
  printf("first read is \'%s\'\n",read_buffer);

  /* reset file pointer to the beginning of the file */
  lseek(file_descriptor, 0, SEEK_SET);
  /* set append flag to prevent overwriting existing text */
  fcntl(file_descriptor, F_SETFL, O_APPEND);
  write(file_descriptor, text2, 10);
  lseek(file_descriptor, 0, SEEK_SET);
  read(file_descriptor, read_buffer,24);
  printf("second read is \'%s\'\n",read_buffer);

  close(file_descriptor);
  unlink("testfile");

  return 0;
}

Output:

first read is 'abcdefghij'
second read is 'abcdefghij0123456789'