FCNTL(2)							System Calls Manual							  FCNTL(2)

NAME

       fcntl - miscellaneous file descriptor control functions

SYNOPSIS

       #include <fcntl.h>

       int fcntl(int fd, int *cmd, [data])

DESCRIPTION

       Fcntl() performs several file descriptor related functions, like duplicating a file descriptor, setting the "close on exec" attribute, etc.
       The fd argument is the file descriptor to operate on, cmd is the command code of the operation to perform, and data is an optional argument
       to give or receive parameters.  The command codes and other symbols and types are declared in <fcntl.h>.  The commands are:

       fcntl(fd, F_DUPFD, int fd2)
	      Returns  a  new file descriptor that is a duplicate of file descriptor fd.  It shares the same file pointer and the same file status
	      flags, but has separate file descriptor flags that are initially off.  The value of the duplicate file descriptor is the first  free
	      file descriptor greater than or equal to fd2.

       fcntl(fd, F_GETFD)
	      Returns  the file descriptor flags associated with file descriptor fd.  The flags are the "close on exec" flag FD_CLOEXEC that, when
	      set, causes the file descriptor to be closed when the process executes another program.  The  Minix-vmd  specific  FD_ASYNCHIO  flag
	      marks a file descriptor for asynchronous I/O operation.

       fcntl(fd, F_SETFD, int flags)
	      Set the file descriptor flags of fd to flags.

       fcntl(fd, F_GETFL)
	      Return  the  file  status  flags and file access modes associated with the file associated with file descriptor fd.  The file status
	      flags are O_NONBLOCK (non blocking I/O) and O_APPEND (append mode).  The	file  access  modes  are  O_RDONLY  (read-only),  O_WRONLY
	      (write-only) and O_RDWR (read-write).  These flags are also used in the second argument of open(2).

       fcntl(fd, F_SETFL, int flags)
	      Set  the	file  status flags of the file referenced by fd to flags.  Only O_NONBLOCK and O_APPEND may be changed.  Access mode flags
	      are ignored.

       The next four commands use a parameter of type struct flock that is defined in <fcntl.h> as:

	      struct flock {
		  short   l_type;     /* F_RDLCK, F_WRLCK, or F_UNLCK */
		  short   l_whence;   /* SEEK_SET, SEEK_CUR, or SEEK_END */
		  off_t   l_start;    /* byte offset to start of segment */
		  off_t   l_len;      /* length of segment */
		  pid_t   l_pid;      /* process id of the locks' owner */
	      };

       This structure describes a segment of a file.  L_type is the lock operation performed on the file segment: F_RDLCK  to  set  a  read  lock,
       F_WRLCK	to  set a write lock, and F_UNLCK to remove a lock.  Several processes may have a read lock on a segment, but only one process can
       have a write lock.  L_whence tells if the l_start offset must be interpreted from the start of the file (SEEK_SET), the current file  posi-
       tion  (SEEK_CUR),  or  the  end	of  the  file (SEEK_END).  This is analogous to the third parameter of lseek(2).  These SEEK_* symbols are
       declared in <unistd.h>.	L_start is the starting offset of the segment of the file.  L_end is the length of the segment.  If zero then  the
       segment	extends  until	end  of  file.	L_pid is the process-id of the process currently holding a lock on the segment.  It is returned by
       F_GETLK.

       fcntl(fd, F_GETLK, struct flock *lkp)
	      Find out if some other process has a lock on a segment of the file associated by file descriptor fd that overlaps with  the  segment
	      described by the flock structure pointed to by lkp.  If the segment is not locked then l_type is set to F_UNLCK.	Otherwise an flock
	      structure is returned through lkp that describes the lock held by the other process.  L_start is set relative to the  start  of  the
	      file.

       fcntl(fd, F_SETLK, struct flock *lkp)
	      Register	a  lock  on  a	segment of the file associated with file descriptor fd.  The file segment is described by the struct flock
	      pointed to by lkp.  This call returns an error if any part of the segment is already locked.

       fcntl(fd, F_SETLKW, struct flock *lkp)
	      Register a lock on a segment of the file associated with file descriptor fd.  The file segment is  described  by	the  struct  flock
	      pointed to by lkp.  This call blocks waiting for the lock to be released if any part of the segment is already locked.

       fcntl(fd, F_FREESP, struct flock *lkp)
	      Free  a segment of disk space occupied by the file associated with file descriptor fd.  The segment is described by the struct flock
	      pointed to by lkp.  The file is truncated in length to the byte position indicated by l_start if l_len is zero.  If l_len is nonzero
	      then the file keeps its size, but the freed bytes now read as zeros.  (Other than sharing the flock structure, this call has nothing
	      to do with locking.)

       fcntl(fd, F_SEEK, u64_t pos)
	      This Minix-vmd specific call sets the file position of the file associated with file descriptor fd to the byte offset  indicated	by
	      the 64-bit number pos.  This is analogous to the call

		     lseek(fd, pos, SEEK_SET)

	      except that F_SEEK can be used on devices larger than 4 gigabyte.

SEE ALSO

       open(2), dup(2), lseek(2), ftruncate(3), int64(3).

DIAGNOSTICS

       Fcntl  returns  a file descriptor, flags, or 0 to indicate success.  On error -1 is returned, with errno set to the appropriate error code.
       The most notable errors are:

       EINTR
	    If a blocked F_SETLKW operation is interrupted by a signal that is caught.

       EAGAIN
	    By F_SETLK if a segment cannot be locked.

       EBADF
	    A bad file descriptor in general, or an attempt to place a write lock on a file that is not open for writing, etc.

       ENOLCK
	    No locks available, the file system code has run out of internal table space.

AUTHOR

       Kees J. Bot (kjb@cs.vu.nl)

																	  FCNTL(2)