fcntl man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

fcntl(2)							      fcntl(2)

NAME
       fcntl() - file control

SYNOPSIS
   Remarks
       The  ANSI  C "" construct denotes a variable length argument list whose
       optional [or required] members are given in the associated comment

DESCRIPTION
       provides for control over open files.  fildes is an open file  descrip‐
       tor.

       The following are possible values for the cmd argument:

	      Fadvise service request (see
			     fadvise(2)).

	      Return  a	 new file descriptor having the following characteris‐
	      tics:

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

			     ·	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
				system calls.

	      Get the file descriptor flags (defined in
			     that  are	associated  with  the  file descriptor
			     fildes.  File  descriptor	flags  are  associated
			     with  a  single file descriptor and do not affect
			     other file descriptors that  refer	 to  the  same
			     file.

	      Set the file descriptor flags (defined in
			     that  are	associated  with  fildes, to the third
			     argument, arg, taken as an integer of  type  (see
			     If	 the  flag  in	the third argument is the file
			     will remain open across otherwise, the file  will
			     be closed upon execution of

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

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

	      Get the first lock that blocks the lock
			     described	by  the variable of type pointed to by
			     the third argument, arg, taken as	a  pointer  to
			     type  The	information  retrieved	overwrites the
			     information passed to in the  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

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

	      This	     cmd is the same as 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.

	      Same as	     except arg is a pointer to instead of

	      Same as	     except arg is a pointer to instead of

	      Same as	     except arg is a pointer to instead of

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

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

	      Gets the current times for the file identified by
			     fildes.  The third argument, arg, is a pointer to
			     the defined in (see

	      Sets the current times for the file identified by
			     fildes.   To  execute  the	 cmd  without	error,
			     requires  superuser  privilege.   The third argu‐
			     ment, arg, is a pointer to the that is defined in
			     The  structure  contains the file's atime (access
			     time), mtime (modification time), and ctime (file
			     attribute change time) values.  Here is the defi‐
			     nition of the structure:

			     This cmd is useful when it is necessary to save a
			     file's  current time values and then, after copy‐
			     ing or moving the file, set back atime and mtime.
			     Note  that	 ctime is not restored to the original
			     value; the value of ctime after  is  file	system
			     dependent.

			     An example using and follows:

	      Sets a share reservation on a file with the specified
			     access  mode and designates which types of access
			     to deny.  The details of the file share  reserva‐
			     tion  request are specified using the third argu‐
			     ment arg, which should be a pointer to a (defined
			     in See the section below.

	      Removes an existing share reservation.

	      If	     fildes  refers  to	 fifo,	the performance of the
			     asynchronous fifo reads or writes may improve  in
			     multiprocessor  environment when multiple threads
			     are operating on the same fildes.	This cmd  will
			     work  only	 if HP's optional product is installed
			     on the system.

			     An example using follows:

       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 can 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 describes the type starting offset relative  offset  size
       and  process ID of the segment of the file to be affected.  The process
       ID field is only used with the 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 to zero (0).  If such a
       lock also has 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 ter‐
       minates.	 Locks are not inherited by a child process in a system call.

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

   File Share Reservations
       File  share  reservations  are an advisory form of access control among
       cooperating processes, on both local and remote machines.   File	 share
       reservations are most commonly used by DOS or Windows emulators and DOS
       based NFS clients.  The system call can	be  used  to  set  file	 share
       reservations using the command.

       A  share	 reservation is described by an fshare structure defined in as
       follows:

       The structure describes the type of access to be requested on the  open
       file  descriptor.  If the command succeeds, it also specifies what type
       of access to deny other processes A single process on the same file can
       hold  several non-conflicting reservations by specifying an identifier,
       unique to the process with each share reservation request.

       Valid values are:

	      Set a file share reservation for read-only access.

	      Set a file share reservation for write-only access.

	      Set a file share reservation for read-write access.

       Valid values are:

	      Set a file share reservation to compatibility mode.

	      Set a file share reservation to deny read access to  other  pro‐
	      cesses.

	      Set  a file share reservation to deny write access to other pro‐
	      cesses.

	      Set a file share reservation to deny read and  write  access  to
	      other processes.

	      Set a file share reservation to not deny read or write access to
	      other
			     processes.

   Oplocks
       An is a type of caching hint used mostly by CIFS clients	 so  they  can
       cache  data  locally.   This  caching helps increase performance by not
       having to read data across a network each time a file operation is per‐
       formed.	 The oplock guarantees that no other remote process is access‐
       ing the file in a way that might lead to data inconsistencies.

       The following arguments are supported for oplocks.

	      Requests an opportunistic lock reservation (oplock) on  a	 file.
	      The supported oplock types are defined in

	      Requests	an  opportunistic  lock reservation (oplock) on a file
	      and will wait
		     (in other words, block) until the request can be granted.

	      Removes all oplocks by pid.

	      Checks to see if an oplock is present on a file.	 The  possible
		     returns values are one of the oplock types defined in

       An  oplock  request is described by an structure which is defined in as
       follows:

       The structure describes the details of the lock being requested on  the
       opened  file descriptor.	 If the command succeeds, it also contains the
       owner ID of the process as well as the type of oplock being  requested.
       The  can	 also  be specified.  The process ID is the requesting process
       with which to associate the oplock.  Optional flags  and	 signal	 value
       can also be specified.

       The  only  field	 in this structure which must be assigned is The other
       fields are either optional or not used and  should  be  initialized  to
       zero (0).

       The fields in the structure are described here:
	      Owner type.  Any integer; however, 0x8000 is reserved.

	      Member ID.
		     Any unique integer of type

	      Type of oplock.
		     is one of these values:
		     Removes an oplock.

		     Request a shared oplock.

		     Request an exclusive oplock.

		     Request a batch oplock.
			    (Requires CIFS stacked file system support)

	      The system ID of the locking process.
		     is an optional value.

	      The process ID of the process that owns the oplock.
		     The  process  ID  does  not  need	to be filled in by the
		     application, because does this internally.

	      This   field is not currently used and is here for future needs.
		     HP recommends that this field be initialized to zero (0).

	      This  field  is the number of retries to gracefully request that
	      an oplock be
		     broken.  After the number of retries are exhausted,  then
		     the  oplock  will	be removed without acknowledgment from
		     the process that owns it.

	      This value represents the wait time in seconds that  the	kernel
	      will wait
		     before  re-sending	 the  oplock  break signal.  The total
		     time that an application can wait for an oplock is multi‐
		     plied by seconds.

	      A value to be sent with signal to a process upon an oplock being
	      broken.

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

NETWORKING FEATURES
   NFS
       The  advisory record-locking capabilities of 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 signal.

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

RETURN VALUE
       Upon  successful	 completion, the value returned depends on cmd as fol‐
       lows:
	      Value of requested hint operation.

	      A new file descriptor.

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

	      Value other than −1.

	      Value of file status flags and access modes.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

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

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

	      Value other than −1.

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

ERRORS
       fails if any of the following conditions occur:
	      cmd is the type of lock is a read lock or	 write	lock  and  the
	      segment  of  a  file  to	be  locked  is already write-locked by
	      another process, or the type is a write lock and the segment  of
	      a	 file to be locked is already read- or write-locked by another
	      process.

	      cmd    is or and the file is mapped in to virtual	 memory	 using
		     the system call (see mmap(2)).

	      cmd    is and conflicts with an existing share reservation.

	      cmd    is	 and this request conflicts with an existing byte lock
		     or share reservation.

	      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.

	      cmd    arg is and the share reservation is  for  read  or	 write
		     access,  and  the	file  descriptor  is  not a valid file
		     descriptor open for reading.

	      cmd    is and the lock is in a deadlock situation.  The deadlock
		     situation	occurs when the lock is blocked by a lock from
		     another process and the lock sleeps and  waits  for  that
		     other lock to become free.

	      cmd    is either or and arg points to an illegal address.

	      cmd    is either or and arg points to an illegal address.

	      cmd    is either or and arg points to an illegal address.

	      cmd    is and the call was interrupted by a signal.

	      cmd    is and arg is negative.

	      cmd    is	 or  and arg or the data it points to is not valid, or
		     fildes refers to a file that does not support locking.

	      cmd    is not a valid command.

	      cmd    is and both and are specified.

	      cmd    is or and the or values are not valid.

	      cmd    is or and arg is invalid.

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

	      cmd    is	 then, either fildes is not referring to fifo, or HP's
		     optional product is not installed.

	      cmd    is and the maximum number of  file	 descriptors  is  cur‐
		     rently open.

	      cmd    is	 or  the  type of lock is a read or write lock, and no
		     more record locks are available (too many	file  segments
		     locked).

	      cmd    is	 or  the type of lock is a read lock or write lock and
		     the file is an NFS file with access bits set for enforce‐
		     ment mode.

	      cmd    is	 or  the  file	is  an	NFS  file,  and a system error
		     occurred on the remote node.

	      [ENOSYS]
		     cmd is or and the arg is which is currently  defined  but
		     not supported.

	      cmd    is or and fildes does not refer to a socket.

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

	      cmd    is and the user does not have superuser privilege.

	      cmd    is the hint is and VM has detected a blocking condition.

WARNINGS
       The oplock support is release specific and as such is not guaranteed to
       be  supported  in  future  releases and/or with the same interface.  HP
       reserves the right to change or remove oplock support at any time.

       If fildes refers to fifo and cmd is set to then:

       1. Major performance improvement can be seen on multiprocessor environ‐
	  ment when multiple threads are operating on the same fifo.

       2. There	 is  no visible performance improvement on systems having less
	  than eight CPUs.

       3. This particular flag should not be set for synchronous fifo reads or
	  writes which otherwise will cause performance regression.

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

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

STANDARDS CONFORMANCE
								      fcntl(2)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net