unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 fcntl(2)							    fcntl(2)




 NAME
      fcntl - file control

 SYNOPSIS
      #include <&lt&lt&lt;fcntl.h>&gt&gt&gt;

      int fcntl(int fildes, int cmd, ... /* arg */);

    Remarks
      The ANSI C ", ..." construct denotes a variable length argument list
      whose optional [or required] members are given in the associated
      comment (/* */).

 DESCRIPTION
      fcntl() provides for control over open files.  fildes is an open file
      descriptor.

      The following are possible values for the cmd argument:

	   F_DUPFD	  Return a new file descriptor having the following
			  characteristics:

			       +  Lowest numbered available file descriptor
				  greater than or equal to the third
				  argument, arg, taken as an integer of type
				  int.

			       +  Same open file (or pipe) as the original
				  file.

			       +  Same file pointer as the original file
				  (that is, both file descriptors share one
				  file pointer).

			       +  Same access mode (read, write or
				  read/write).

			       +  Same file status flags (that is, both file
				  descriptors share the same file status
				  flags).

			       +  The close-on-exec flag associated with the
				  new file descriptor is set to remain open
				  across exec(2) system calls.

	   F_GETFD	  Get the close-on-exec flag associated with the
			  file descriptor fildes.  If the low-order bit is 0
			  the file will remain open across exec(2),
			  otherwise the file will be closed upon execution
			  of exec(2).




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 fcntl(2)							    fcntl(2)




	   F_SETFD	  Set the close-on-exec flag associated with fildes
			  to the low-order bit of the third argument, arg,
			  taken as an integer of type int (see F_GETFD).

	   F_GETFL	  Get file status flags and access modes; see
			  fcntl(5).

	   F_SETFL	  Set file status flags to the third argument, arg,
			  taken as an integer of type int.  Only certain
			  flags can be set; see fcntl(5).  It is not
			  possible to set both O_NDELAY and O_NONBLOCK.

	   F_GETLK	  Get the first lock that blocks the lock described
			  by the variable of type struct flock pointed to by
			  the third argument, arg, taken as a pointer to
			  type struct flock.  The information retrieved
			  overwrites the information passed to fcntl() in
			  the flock structure.	If no lock is found that
			  would prevent this lock from being created, the
			  structure is passed back unchanged, except that
			  the lock type is set to F_UNLCK.

	   F_SETLK	  Set or clear a file segment lock according to the
			  variable of type struct flock pointed to by the
			  third argument, arg, taken as a pointer to type
			  struct flock (see fcntl(5)).	The cmd F_SETLK is
			  used to establish read (F_RDLCK) and write
			  (F_WRLCK) locks, as well as to remove either type
			  of lock (F_UNLCK).  If a read or write lock cannot
			  be set, fcntl() returns immediately with an error
			  value of -1.

	   F_SETLKW	  This cmd is the same as F_SETLK except that if a
			  read or write lock is blocked by other locks, the
			  process will sleep until the segment is free to be
			  locked.

	   F_GETOWN	  If fildes refers to a socket, fcntl() returns the
			  process or process group ID specified to receive
			  SIGURG signals when out-of-band data is available.
			  Positive values indicate a process ID; negative
			  values, other than -1, indicate a process group
			  ID.

	   F_SETOWN	  If fildes refers to a socket, fcntl() sets the
			  process or process group ID specified to receive
			  SIGURG signals when out-of-band data is available,
			  using the value of the third argument, arg, taken
			  as type int.	Positive values indicate a process
			  ID; negative values, other than -1, indicate a
			  process group ID.



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 fcntl(2)							    fcntl(2)




	   F_GETLK64	  Same as F_GETLK, except arg is a pointer to struct
			  flock64 instead of struct flock.

	   F_SETLK64	  Same as F_SETLK, except arg is a pointer to struct
			  flock64 instead of struct flock.

	   F_SETLKW64	  Same as F_SETLKW, except arg is a pointer to
			  struct flock64 instead of struct flock.

	   A read lock prevents any other process from write-locking the
	   protected area.  More than one read lock can exist for a given
	   segment of a file at a given time.  The file descriptor on which
	   a read lock is being placed must have been opened with read
	   access.

	   A write lock prevents any other process from read-locking or
	   write-locking the protected area.  Only one write lock may exist
	   for a given segment of a file at a given time.  The file
	   descriptor on which a write lock is being placed must have been
	   opened with write access.

	   The structure flock describes the type (l_type), starting offset
	   (l_whence), relative offset (l_start), size (l_len), and process
	   ID (l_pid) of the segment of the file to be affected.  The
	   process ID field is only used with the F_GETLK cmd to return the
	   value of a block in lock.  Locks can start and extend beyond the
	   current end of a file, but cannot be negative relative to the
	   beginning of the file.  A lock can be set to always extend to the
	   end of file by setting l_len to zero (0).  If such a lock also
	   has l_start set to zero (0), the whole file will be locked.
	   Changing or unlocking a segment from the middle of a larger
	   locked segment leaves two smaller segments for either end.
	   Locking a segment already locked by the calling process causes
	   the old lock type to be removed and the new lock type to take
	   effect.  All locks associated with a file for a given process are
	   removed when a file descriptor for that file is closed by that
	   process or the process holding that file descriptor terminates.
	   Locks are not inherited by a child process in a fork(2) system
	   call.

	   When enforcement-mode file and record locking is activated on a
	   file (see chmod(2)), future read() and write() system calls on
	   the file are affected by the record locks in effect.

    Application Usage
      Because in the future the external variable errno will be set to
      EAGAIN rather than EACCES when a section of a file is already locked
      by another process, portable application programs should expect and
      test for either value.  For example:





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 fcntl(2)							    fcntl(2)




	   flk->&gt&gt&gt;l_type = F_RDLCK;
	      if (fcntl(fd, F_SETLK, flk) == -1)
		 if ((errno == EACCES) || (errno == EAGAIN))
		       /*
			* section locked by another process,
			* check for either EAGAIN or EACCES
			* due to different implementations
			*/
		  else if ...
		       /*
			* check for other errors
			*/

 NETWORKING FEATURES
    NFS
      The advisory record-locking capabilities of fcntl() are implemented
      throughout the network by the ``network lock daemon'' (see lockd(1M)).
      If the file server crashes and is rebooted, the lock daemon attempts
      to recover all locks associated with the crashed server.	If a lock
      cannot be reclaimed, the process that held the lock is issued a
      SIGLOST signal.

	   Record locking, as implemented for NFS files, is only advisory.

 RETURN VALUE
      Upon successful completion, the value returned depends on cmd as
      follows:

	   F_DUPFD	  A new file descriptor.

	   F_GETFD	  Value of close-on-exec flag (only the low-order
			  bit is defined).

	   F_SETFD	  Value other than -1.

	   F_GETFL	  Value of file status flags and access modes.

	   F_SETFL	  Value other than -1.

	   F_GETLK	  Value other than -1.

	   F_SETLK	  Value other than -1.

	   F_SETLKW	  Value other than -1.

	   F_GETOWN	  Value of process or process group ID specified to
			  receive SIGURG signals when out-of-band data is
			  available.

	   F_SETOWN	  Value other than -1.




 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 fcntl(2)							    fcntl(2)




	   F_GETLK64	  Value other than -1.

	   F_SETLK64	  Value other than -1.

	   F_SETLKW64	  Value other than -1.

      Otherwise, a value of -1 is returned and errno is set to indicate the
      error.

 ERRORS
      fcntl() fails if any of the following conditions occur:

	   [EBADF]	  fildes is not a valid open file descriptor, or was
			  not opened for reading when setting a read lock or
			  for writing when setting a write lock.

	   [EMFILE]	  cmd is F_DUPFD and the maximum number of file
			  descriptors is currently open.

	   [EMFILE]	  cmd is F_SETLK or F_SETLKW, the type of lock is a
			  read or write lock, and no more file-locking
			  headers are available (too many files have
			  segments locked).

	   [EINVAL]	  cmd is F_DUPFD and arg is greater than or equal to
			  the maximum number of file descriptors.

	   [EINVAL]	  cmd is F_DUPFD and arg is negative.

	   [EINVAL]	  cmd is F_GETLK, F_SETLK, or F_SETLKW, and arg or
			  the data it points to is not valid, or fildes
			  refers to a file that does not support locking.

	   [EINVAL]	  cmd is not a valid command.

	   [EINVAL]	  cmd is F_SETFL and both O_NONBLOCK and O_NDELAY
			  are specified.

	   [EINTR]	  cmd is F_SETLKW and the call was interrupted by a
			  signal.

	   [EACCES]	  cmd is F_SETLK, the type of lock (l_type) is a
			  read lock (F_RDLCK) or write lock (F_WRLCK) and
			  the segment of a file to be locked is already
			  write-locked by another process, or the type is a
			  write lock (F_WRLCK) and the segment of a file to
			  be locked is already read- or write-locked by
			  another process.

	   [ENOLCK]	  cmd is F_SETLK or F_SETLKW, the type of lock is a
			  read or write lock, and no more file-locking



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 fcntl(2)							    fcntl(2)




			  headers are available (too many files have
			  segments locked), or no more record locks are
			  available (too many file segments locked).

	   [ENOLCK]	  cmd is F_SETLK or F_SETLKW, the type of lock
			  (l_type) is a read lock (F_RDLCK) or write lock
			  (F_WRLCK) and the file is an NFS file with access
			  bits set for enforcement mode.

	   [ENOLCK]	  cmd is F_GETLK, F_SETLK, or F_SETLKW, the file is
			  an NFS file, and a system error occurred on the
			  remote node.

	   [EOVERFLOW]	  cmd is F_GETLK and the blocking lock's starting
			  offset or length would not fit in the caller's
			  structure.

	   [EDEADLK]	  cmd is F_SETLKW, when the lock is blocked by a
			  lock from another process and sleeping (waiting)
			  for that lock to become free.	 This causes a
			  deadlock situation.

	   [EAGAIN]	  cmd is F_SETLK or F_SETLKW, and the file is mapped
			  in to virtual memory via the mmap() system call
			  (see mmap(2)).

	   [EFAULT]	  cmd is either F_GETLK, F_SETLK, or F_SETLKW, and
			  arg points to an illegal address.

	   [ENOTSOCK]	  cmd is F_GETOWN or F_SETOWN, and fildes does not
			  refer to a socket.

 AUTHOR
      fcntl() was developed by HP, AT&T and the University of California,
      Berkeley.

 SEE ALSO
      lockd(1M), statd(1M), chmod(2), close(2), creat64(2), exec(2),
      lockf(2), open(2), read(2), write(2), fcntl(5).

 STANDARDS CONFORMANCE
      fcntl(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1












 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000