fcntl -- Control Open File Descriptors

SYNOPSIS

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

 int fcntl(int filedes, int action, argument);

DESCRIPTION

fcntl controls open OpenEdition file descriptors and sockets. filedes is the file descriptor. action is the action to be performed on the file or socket. For a nonintegrated socket, the only actions that can be specified are F_GETFL and F_SETFL. The third argument required by some actions is argument. The type of this argument depends on the action.

You can specify the following actions with fcntl:

F_DUPFD
duplicates the file descriptor and returns the lowest available file descriptor greater than or equal to argument. This duplicate file descriptor refers to the same file as filedes.
F_DUPFD2
duplicates the file descriptor and returns a file descriptor specified by argument. The file descriptor specified by argument is closed and is then used as the new file descriptor. This duplicate file descriptor refers to the same file as filedes.
F_GETFD
returns the file descriptor flags for filedes. This action has no effect if filedes is a non-integrated socket.
F_SETFD
sets the file descriptor flags for filedes. New flag settings are specified by argument. This action has no effect if filedes is a nonintegrated socket.
F_GETFL
returns the file-status flags and file access mode flags for filedes. If filedes is a nonintegrated socket, only the setting of O_NONBLOCK is significant.
F_SETFL
Sets the flag status flags for filedes. New flag settings are specified by argument. fcntl does not change the file access mode. If filedes is a nonintegrated socket, only the O_NONBLOCK setting may be changed.
F_GETLK
returns locking information for a file.
F_SETLK
sets or clears a file segment lock.
F_SETLKW
sets or clears a file segment lock. If a lock is blocked by other locks, fcntl waits until it can set or clear the lock.
F_CLOSFD
closes a range of file descriptors. argument specifies the upper limit of the range. filedes is the lower limit. If argument is a - 1, all file descriptors greater than or equal to fildes are closed.

The following flags and masks are defined in <fcntl.h>:

O_ACCMODE
This mask defines the bits that comprise the file access mode. O_ACCMODE can be ANDed with the value stored by the F_GETFL action to isolate the file access mode.
FD_CLOEXEC
If set to 1, requests that the file descriptor be closed if the process calls an exec function. If set to 0, the file descriptor remains open if the process calls exec.
O_APPEND
If set to 1, every write operation begins at the end of the file.
FD_CLOFORK
If set to 1, requests that, when a fork occurs, the file descriptor be closed for the child process. If set to 0, the file descriptor remains open for any child process.
O_NONBLOCK
If set to 1, read and write operations return an error if I/O cannot be immediately performed. If set to 0, read and write operations wait until I/O can be performed. Note that the traditional BSD file status flag FNDELAY is defined in <fcntl.h> as a synonym for O_NONBLOCK.
O_RDONLY
This file access mode value indicates the file is opened for input only.
O_RDWR
This file access mode value indicates the file is opened for both input and output.
O_WRONLY
This file access mode value indicates the file is opened for output only.

RETURN VALUE

fcntl returns the value specified by action. The fcntl function returns a - 1 if it is not successful.

PORTABILITY

The F_CLOSFD action and the FD_CLOFORK flag are extensions defined by IBM to the POSIX.1 standard.

EXAMPLES

This example updates a counter stored in the first four bytes of an HFS file. It uses the record-locking feature of fcntl to ensure that two processes running the same program do not update the file simultaneously. 
     /* This example requires cxompilation with the posix option. */
  #include <sys/types.h>
  #include <fcntl.h>
  #include <stdio.h>
  #include <stdlib.h>

  main() {
     int fd;
     long count;
     struct flock lock;
     int rc;

        /* If the file does not yet exist, create it, and treat the */
        /*  counter as 0.  If the file does exist, do not truncate  */
        /*  it, as we need the old data.                            */
     fd = open("/u/yvonne/counter", O_CREAT | O_RDWR,
               S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP);
     if (fd < 0) {
        perror("open error");
        exit(EXIT_FAILURE);
     }
     lock.l_type = F_WRLCK;
     lock.l_whence = SEEK_SET;
     lock.l_start = 0L;
     lock.l_len = sizeof(count);
     rc = fcntl(fd, F_SETLKW, &lock);            /* Lock bytes 0-3. */
     if (rc == -1) {
        perror("fcntl F_WRLCK error");
        exit(EXIT_FAILURE);
     }
     rc = read(fd, &count, sizeof(count));
     if (rc == -1) {
        perror("read");
        exit(EXIT_FAILURE);
     }
     if (rc < sizeof(count)) count = 0;

        /* If too few bytes read, assume count 0. */
     rc = lseek(fd, 0L, SEEK_SET);
     if (rc != 0) {
        perror("lseek error");
        exit(EXIT_FAILURE);
     }
     ++count;
     rc = write(fd, &count, sizeof(count));
     if (rc != sizeof(count)) {
        perror("write error");
        exit(EXIT_FAILURE);
     }

        /* The lock will be released when the file is closed,       */
        /*  but to be polite we will release it explicitly.         */
     lock.l_type = F_UNLCK;
     rc = fcntl(fd, F_SETLK, &lock);           /* Unlock bytes 0-3. */
     if (rc == -1) {
        perror("fcntl F_UNLCK error");
        exit(EXIT_FAILURE);
     }
     fclose(fd);
     exit(EXIT_SUCCESS);
  }

SEE ALSO

Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.