


      FCNTL(2)                    (UNIX 5.0)                   FCNTL(2)



      NAME
           fcntl - file control

      SYNTAX
           #include <fcntl.h>

           int fcntl (fildes, cmd, arg)
           int fildes, cmd, arg;

      DESCRIPTION
           Fcntl provides for control over open files.  Fildes is an
           open file descriptor obtained from a creat, open, dup, or
           fcntl.  system call.

           The cmds available are:

           F_DUPFDReturn a new file descriptor as follows:

                  Lowest numbered available file descriptor greater
                  than or equal to arg.

                  Same open file as the original file.

                  Same file pointer as the original file (i.e., both
                  file descriptors share one file pointer).

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

                  Same file status flags (i.e., 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_GETFDGet 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, otherwise the file
                  will be closed upon execution of exec.

           F_SETFDSet the close-on-exec flag associated with fildes to
                  the low-order bit of arg (0 or 1 as above).

           F_GETFLGet file status flags.

           F_SETFLSet file status flags to arg.  Only certain flags can
                  be set; see fcntl(5).

           F_GETLKGet the first lock which blocks the lock description
                  given by the variable of type struct flock pointed to
                  by arg.  The information retrieved overwrites the
                  information passed to fcntl in the flock structure.



      Page 1                                         (73 A2 02MTA REV1)






      FCNTL(2)                    (UNIX 5.0)                   FCNTL(2)



                  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 will be set
                  to F_UNLCK.

           F_SETLKSet or clear a file segment lock according to the
                  variable of type struct flock pointed to by arg (see
                  fcntl(5)).  The cmd F_SETLK 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, fcntl will return
                  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.

           A read lock prevents any process from write locking the
           protected area.  More than one read lock may 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 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.


























      Page 2                                         (73 A2 02MTA REV1)






      FCNTL(2)                    (UNIX 5.0)                   FCNTL(2)



           The structure flock (see fcntl(5)) 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 values for a
           blocking lock.  Locks may start and extend beyond the
           current end of a file, but may not be negative relative to
           the beginning of the file.  A lock may be set to always
           extend to the end of the 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 setment from
           the middle of a larger locked segment leaves two smaller
           segments for either end.  Locking a segment that is already
           locked by the calling process causes the old lock type to be
           removed and the new lock type to take affect.  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 mandatory file/record locking is in set on a file, see
           chmod(2), future read and write system calls on the file
           will be affected by the record locks in effect.

           Fcntl will fail if one or more of the following are true:

                Fildes is not a valid open file descriptor.  [EBADF]

                Cmd is F_DUPFD and 64 file descriptors are currently
                open.  [EMFILE]

                Cmd is F_DUPFD and arg is negative or greater than 64.
                Cmd is F_GETLK, F_SETLK, or SETLKW and arg or the data
                it points to is not valid.  [EINVAL]

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

                Cmd is F_SETLK or F_SETLKW, the type of lock is a read
                or write lock and there are no more record locks
                available (too many file segments locked).  [ENOLCK]

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




      Page 3                                         (73 A2 02MTA REV1)






      FCNTL(2)                    (UNIX 5.0)                   FCNTL(2)



      RETURN VALUE
           Upon successful completion, the value returned depends on
           cmd as follows:
                F_DUPFDA new file descriptor.
                F_GETFDValue of flag (only the low-order bit is
                       defined).
                F_SETFDValue other than -1.
                F_GETFLValue of file flags.
                F_SETFLValue other than -1.
                F_GETLKValue other than -1.
                F_SETLKValue other than -1.
                F_SETLKW
                       Value other than -1.
           Otherwise, a value of -1 is returned and errno is set to
           indicate the error.

      SEE ALSO
           close(2), dup(2), dup2(2), exec(2), open(2), read(2),
           write(2), fcntl(5).




































      Page 4                                         (73 A2 02MTA REV1)



