fcntl man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

fcntl(2)							      fcntl(2)

Name
       fcntl - file control

Syntax
       #include <fcntl.h>

       res = fcntl (fd, request, arg)
       int res;
       int fd, request, arg

Arguments
       The following arguments can be used with

       fd	 Descriptor  to	 be  operated  on.   Depending on the function
		 selected by the request argument, the fd argument  can	 be  a
		 file  descriptor  returned  by	 an  system  call, or a socket
		 descriptor returned by a system call.

       request	 Defines what you want done. The possible values  are  defined
		 in See the Description section for more information.

       arg	 Varies	 according  to the request argument.  See the Descrip‐
		 tion section for more information.

Description
       The system call provides for control over descriptors.  The descriptors
       can  be	either	file descriptors returned by the system call or socket
       descriptors returned by the system call.

       Possible request arguments are the following:

   F_DUPFD - Return New Descriptor
       The shell provides an example of when a new descriptor is useful.  Sup‐
       pose the shell receives a command such as:
       cat > myfile
       The  shell  needs  to  redirect the output of the command from the file
       descriptor 1 (standard output) to a new file named The shell issues the
       call, using the old file descriptor of 1, to obtain a new file descrip‐
       tor for the file

       F_DUPFD	    When request is set for F_DUPFD:

		    The call returns a new descriptor.	The new file  descrip‐
		    tor returned has the following characteristics:

		    ·  The  file  descriptor  returned	is the lowest numbered
		       available descriptor that is greater than or  equal  to
		       the argument arg.

		    ·  The  descriptor	has  the same object references as the
		       original descriptor.  That is,  if  the	original  file
		       descriptor  referred to a file, the new file descriptor
		       refers to a file.  If the original descriptor  referred
		       to  a  socket,  the  new	 file  descriptor  refers to a
		       socket.

		    ·  The new descriptor shares the same file pointer if  the
		       object was a file.  (A file pointer points to an inode,
		       which in turn points to a file.	Thus, the new descrip‐
		       tor refers to the same file as the old descriptor.)

		    ·  The  new descriptor has the same access mode as the old
		       descriptor (read, write, or read/write).

		    ·  The new descriptor shares the same file status flags as
		       the  old	 file  descriptor.   (See  the	discussion  of
		       F_GETFL and F_SETFL for a description  of  file	status
		       flags.)

		    ·  The  close-on-exec  flag	 associated  with the new file
		       descriptor is set to remain open across	system	calls.
		       (See  the  discussion  of  F_GETFD  and	F_SETFD	 for a
		       description of the close-on-exec flag.)

   F_GETFD and F_SETFD - Close-on-exec Flag
       Each file descriptor points to an entry in an array  of	file  pointers
       that,  among other things, define certain characteristics for the file.
       One such characteristic is the close-on-exec flag.  This	 flag  defines
       whether or not a file remains open across calls to If cleared, the file
       descriptor remains open in the new image loaded by the call to If  set,
       the file descriptor is closed in the new image loaded by the call to

       F_GETFD	    When request is set to F_GETFD:

		    The	 call  returns	the close-on-exec flag associated with
		    the file descriptor fd.  If the low-order bit of the value
		    returned by is 0, the file remains open across calls to If
		    the low-order bit of the value returned by is 1, the  file
		    descriptor is closed across calls to

       F_SETFD	    When request is set to F_SETFD:

		    The call sets the close-on-exec flag associated with fd to
		    the low-order bit of arg (0 or 1).

   F_GETFL and	F_SETFL - Descriptor Status Flags
       Each file descriptor points to an entry in an array  of	file  pointers
       that,  among  other things, define the file's current status.  One such
       item of status, for example, is whether or not input/output  operations
       to a file are currently blocked.

       You might want to program your process to allow blocking so that a user
       who runs your process in the background, while doing other work in  the
       foreground,  need  not  see output from the background job displayed on
       the screen.

       These and other status indicators are discussed in the list  that  fol‐
       lows.  Some status indicators do not apply to all types of descriptors.
       The O_APPEND status, for example, is meaningless for sockets.

       F_GETFL	    When request is set to F_GETFL:

		    The call returns the file's descriptor status flags.   The
		    following  names  have  been  defined  in for these status
		    flags:

		    O_NDELAY	 Nonblocking I/O.  If no data is available  to
				 a  call, or if a write operation would block,
				 the call returns -1 with the  error  [EWOULD‐
				 BLOCK].  The flag FNDELAY is an obsolete syn‐
				 onym for O_NDELAY.

		    O_FSYNC	 (O_SYNC) Synchronous write flag.  Forces sub‐
				 sequent file writes to be done synchronously.
				 For further information, see The flag	OFSYN‐
				 CRON is an obsolete synonym for FSYNCRON.

		    O_APPEND	 Force	each  write  to	 append	 at the end of
				 file.	This corresponds to the	 action	 taken
				 with the O_APPEND flag of The flag FAPPEND is
				 an obsolete synonym for O_APPEND.

		    FASYNC	 Enable the SIGIO signal to  be	 sent  to  the
				 process  group	 when  I/O  is	possible.  For
				 example, send SIGIO when data is available to
				 be read.

		    O_NONBLOCK	 POSIX environment, nonblocking I/O flag.  See
				 O_NDELAY request for  description  of	opera‐
				 tion.	 The  flag FNBLOCK is an obsolete syn‐
				 onym for O_NONBLOCK.

       F_SETFL	    When request is set to F_SETFL:

		    The call sets descriptor status  flags  specified  in  arg
		    (see  F_GETFL).  Refer  to	the  F_SETOWN section for more
		    information.

   F_GETOWN and F_SETOWN - Get Or Set Owner
       With these requests, your process can recognize the software interrupts
       SIGIO or SIGURG.	 As described in SIGIO is a signal indicating that I/O
       is possible on a descriptor.   SIGURG  indicates	 an  urgent  condition
       present on a socket.

       F_GETOWN	    When request is set to F_GETOWN:
		    The call returns the process ID or process group currently
		    receiving SIGIO and SIGURG signals.	  Process  groups  are
		    returned as negative values.

       F_SETOWN	    When request is set to F_SETOWN:
		    The	 call  sets  the  process  or process group to receive
		    SIGIO and SIGURG signals; process groups are specified  by
		    supplying arg as negative.	 Otherwise, arg is interpreted
		    as a process ID. See also the F_SETFL request, which  sets
		    descriptor status flags, and the description of the FASYNC
		    flag in the F_GETFL section.

   F_GETLK, F_SETLK, and F_SETLKW - Locking File Regions
       With these requests, your process can:

       ·  Test a file for a region that might have been read-locked or	write-
	  locked by another process.

       ·  Set or clear a file region read or write lock.

       ·  Set  a file region read or write lock, sleeping, if necessary, until
	  locks previously set by other processes are unlocked.

       When a read lock has been set on a segment of a file,  other  processes
       can also set read locks on that file segment or portions thereof.

       A read lock prevents any other process from write locking the protected
       area.  More than one read lock can exist for a given region 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	region.	  Only	one write lock can exist for a
       given region 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.

       Locks can start and extend beyond the current end of a file, but cannot
       be negative relative to the beginning of the file.

       Changing or unlocking a region from  the	 middle	 of  a	larger	locked
       region  leaves  two smaller regions with the old setting at either end.
       Locking a region that is already locked by the calling  process	causes
       the old lock 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 system call.

       F_GETLK	    When request is set to F_GETLK:

		    The call gets the lock information for  a  read  or	 write
		    locked  region.   In the call, you pass a lock description
		    in a variable of type struct flock pointed to by arg.

		    If the region defined in the flock	structure  is  already
		    locked  by	a process other than the caller, a description
		    of the existing lock is returned in the  flock  structure.
		    If	no  lock  is  found  that would prevent this lock from
		    being created, then the structure is passed back unchanged
		    except for the lock type which is set to F_UNLCK.

		    The flock structure is defined as follows:
		    struct flock {
			    short    l_type;
			    short    l_whence;
			    long     l_start;
			    long     l_len;
			    int	     l_pid;
		    };
		    Data Passed in flock:

		    In	the  data  you pass in flock, the l_type value defines
		    the lock type to be tested for: F_RDLCK for	 a  read  lock
		    and F_WRLCK for a write lock.

		    The l_whence value defines the point from which the start‐
		    ing byte of the region is to be measured.  If l_whence  is
		    0,	the  value in l_start is taken as the starting byte of
		    the region.	 If l_whence is 1,  the	 current  file	offset
		    plus  the value of l_start is taken as the starting point.
		    If l_whence is 2, the file size plus the value of  l_start
		    is taken as the starting point.

		    The	 l_len value is the length of the region to be tested,
		    in bytes.  If l_len is  zero,  the	length	to  be	tested
		    extends  to the end of file.  If l_len is zero and l_start
		    is zero, the whole file is to be tested.  If l_len is neg‐
		    ative,  the	 area  affected	 starts at l_start + l_len and
		    ends at l_start - 1.

		    The l_pid value has no significance in the data passed.

		    Data Returned in flock:

		    The l_type value can be F_RDLCK if the  region  passed  is
		    under  a  read lock.  F_WRLCK means that the region passed
		    is under a write lock.  F_UNLCK means that the  region  is
		    not	 currently  locked  by	any process that would prevent
		    this lock from being  created;  for	 example,  the	region
		    might be locked by the caller.

		    The l_whence, l_start, and l_len values have similar mean‐
		    ings as discussed under  Data  Passed,  except  that  they
		    define the region currently under read or write lock.

		    The	 l_pid	value  is only used with F_GETLK to return the
		    value for a blocking lock.	An example of a blocking  lock
		    is	a write lock currently set by a process other than the
		    calling process.

       F_SETLK	    When request is set to F_SETLK:

		    You set or clear a file region lock according to the vari‐
		    able  of  l_type  in  the  struct flock pointed to by arg.
		    (The flock structure is shown  under  the  description  of
		    F_GETLK, preceding.)

		    The	 l_type	 value is used to establish read (F_RDLCK) and
		    write (F_WRLCK) locks, as well as remove  either  type  of
		    lock  (F_UNLCK).   If  a read or write lock cannot be set,
		    will return immediately with an error value of -1.

       F_SETLKW	    When request is set to F_SETLKW:

		    The call takes the same action as for F_SETLK, except that
		    if	a  read	 or  write lock is blocked by other locks, the
		    process sleeps until the segment is free to be locked.

       Files and region locking are supported over  the	 Network  File	System
       (NFS) services if you have enabled the NFS locking service.

Return Values
       Upon successful completion, the value returned depends upon the request
       argument as follows:
		 F_DUPFDA new file descriptor.
		 F_GETFDValue of flag (only the low-order bit is defined).
		 F_GETFLValue of flags.
		 F_GETOWNValue of file descriptor owner.
		 otherValue other than -1.
       Otherwise, a value of -1 is returned and errno is set to	 indicate  the
       error.

Diagnostics
       The fails if under the following conditions:

       [EBADF]	      The fildes argument is not a valid open file descriptor.

       [EBADF]	      The  environment	defined is POSIX, the request argument
		      is F_SETLK or F_SETLKW, the type of lock, l_type,	 is  a
		      shared  lock  (F_RDLCK),	and fildes is not a valid file
		      descriptor open  for  reading,  or  the  type  of	 lock,
		      l_type,  is  an  exclusive lock (F_WRLCK), and fildes is
		      not a valid file descriptor open for writing.

       [EFAULT]	      The arg is pointing to an address outside the  process's
		      allocated space.

       [EINVAL]	      The  request argument is F_DUPFD, and arg is negative or
		      greater than the maximum allowable number.  For  further
		      information, see

       [EINVAL]	      The  request  argument  is F_SETSYN, to change the write
		      mode of a file to synchronous, and this operation is not
		      valid  for  the  file descriptor.	 For example, the file
		      was opened for read-only operations.

       [EINVAL]	      The request argument is F_GETLK,F_SETLK, or  SETLKW  and
		      the data arg points to is not valid.

       [EINVAL]	      The request argument is invalid.

       [EINVAL]	      The  fildes argument refers to a file that does not sup‐
		      port locking.

       [EACCES]	      The request argument is F_SETLK,	the  type  of  lock  (
		      l_type  )	 is  a read (F_RDLCK) or write (F_WRLCK) lock,
		      and the region of the file to be locked is already write
		      locked by another process.  Or, the type is a write lock
		      and the region of the file to be locked is already  read
		      or  write	 locked	 by  another process.  Or, the file is
		      remotely mounted and the	NFS  locking  service  is  not
		      enabled.

       [EMFILE]	      The request argument is F_DUPFD, and the maximum allowed
		      number of file descriptors is currently open, or no file
		      descriptors greater than or equal to arg are available.

       [ENOSPC]	      The request argument is F_SETLK or F_SETLKW, the type of
		      lock is a read or write lock, and there are no more file
		      locking  headers available (too many files have segments
		      locked).	Or, there are no more record  locks  available
		      (too many file segments locked).

       [EDEADLK]      The  request  argument  is  F_SETLKW,  and  the  lock is
		      blocked by some lock from another process that is sleep‐
		      ing (waiting) for that lock to become free.  This detec‐
		      tion avoids a deadlock situation.

       [EOPNOTSUPP]   Attempting an operation that is not valid for  the  file
		      descriptor.  This can occur if the file descriptor argu‐
		      ment, fd, points to a socket address,  and  the  request
		      argument is only valid for files.

       [EINTR]	      The  request  argument  is F_SETLKW and the function was
		      interrupted by a signal.

Environment
       The description differs from the POSIX and  XPG3	 definitions  in  that
       ENOLCK is not a possible error condition.

See Also
       close(2), execve(2), getdtablesize(2), open(2), sigvec(2), lockd(8c)

								      fcntl(2)
[top]

List of man pages available for Ultrix

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