fffcntl(3C)

NAME
     fffcntl - Performs functions on files opened using flexible file I/O

SYNOPSIS
     #include <ffio.h>

     int fffcntl (int fd, int cmd, void *arg, struct ffsw *stat);

DESCRIPTION
     The fffcntl function performs a variety of functions on files opened
     by ffopen or ffopens, using flexible file I/O (FFIO).  Arguments are
     as follows:

     fd     Number returned by function ffopen or ffopens.

     cmd    Specifies values defined in header file ffio.h.  See under the
            next heading, VALUES FOR cmd ARGUMENT.

     arg    The type and value of arg is cmd specific.  See preceding
            descriptions.

     stat   Pointer to the status return structure.

   Values for cmd Argument
     The following values can be used for the cmd argument introduced
     above:

     FC_ASPOLL
           Checks for completion of an asynchronous FFIO request.  Argument
           arg is a pointer to a structure of type struct ffsw, which had
           previously been passed to an asynchronous FFIO request.  The
           purpose of this call is to pass control to the underlying layers
           to do intermediate processing or cleanup on the request.  If the
           request is complete, fields in the status return structure are
           set as described under function ffreada(3C).

     FC_GETINFO
           Gets information about the layers connected to this open file.
           arg is a pointer to structure ffc_info_s.  The information
           returned in this structure is as follows:

           ffc_flags
                 Flag word containing attributes of the file/connection.
                 These bit masks are defined in header file ffio.h and are
                 set if true, as follows:

                 FFC_STRM       Can handle stream I/O.

                 FFC_REC        Can handle records.

                 FFC_WEOF       Can represent EOF.

                 FFC_WEOD       Can represent EOD (always set).

                 FFC_BKSP       Can handle backspace.

                 FFC_BKFIL      Can handle backfile.

                 FFC_SEEKA      Can seek absolute.

                 FFC_SEEKR      Can seek relative.

                 FFC_SEEKE      Can seek to end.

                 FFC_POSREC     Can position by record number.

                 FFC_POSFIL     Can position by EOF mark.

                 FFC_RWND       Can rewind by seek(x,0,0).

                 FFC_FIXD       Can do fixed-length records.

                 FFC_VAR        Can do variable-length records.

                 FFC_BINARY     Can do binary data.

                 FFC_CODED      Can do formatted (character) data.

                 FFC_RDM        Can do random I/O (no truncation).

                 FFC_SEQ        Can do sequential I/O.

                 FFC_ASYNC      Can do asynchronous I/O.  (All layers have
                                asynchronous entry points, but this bit
                                tells whether the behavior is actually
                                async.)

                 FFC_WRTRUNC    Write implies truncation.

                 FFC_NOTRN      Does no transformation on data; no control
                                words are added or subtracted.  Data is not
                                changed.

           ffc_gran
                 Minimum granularity.  This is the smallest size in bits of
                 a valid data transfer.  For example, the system call layer
                 has an ffc_gran of 8, as it can handle a byte as its
                 smallest unit of data transfer.  Some CDC record formats
                 have a granularity of 60.

           ffc_reclen
                 Valid only for fixed length records.  This is the record
                 length in bits.

           ffc_fd
                 Lowest level file descriptor for the layer that makes
                 system calls.  This is not always available, or may not be
                 meaningful for some layers or combinations of layers.
                 This is -1 if no descriptor is available.

     FC_GETLK
           Performs an fcntl call with cmd F_GETLK.  arg is a pointer to
           structure flock (defined in sys/fcntl.h), which is used in the
           fcntl call.  Currently supported only by the syscall and system
           layers.

     FC_GETLKW
           Performs an fcntl call with cmd F_GETLKW.  arg is a pointer to
           structure flock (defined in sys/fcntl.h), which is used in the
           fcntl call.  Currently supported only by the syscall and system
           layers.

     FC_RECALL
           Awaits completion of an asynchronous FFIO request.  Argument arg
           is a pointer to a structure of type struct ffsw, which is the
           status return structure of the asynchronous request.  Function
           fffcntl waits for completion of the asynchronous request, if
           necessary.  Fields in the status return structure are set as
           described under function ffreada(3C).

     FC_SCRATCH
           Specifies that a file is to be deleted at close time.  The arg
           argument is a pointer to int.  On exit, *arg is set to contain
           zero or more of the following result bits:

           SCR_NOFLUSH       Set if ffclose processing has been optimized
                             to suppress buffer flushing.

           SCR_SINGLELINK    Set if the file is not a pipe or a tty, has a
                             link count equal to one, and is not a
                             symbolicly linked file.

           SCR_UNLINKED      Set if this fffcntl call has successfully
                             unlinked the file.

     FC_SETLK
           Performs an fcntl call with cmd F_SETLK.  arg is a pointer to
           structure flock (defined in sys/fcntl.h), which is used in the
           fcntl call.  Currently supported only by the syscall and system
           layers.

     FC_STAT
           Returns a structure much like the one returned by the fstat (see
           stat(2))  system call.  arg is a pointer to a ffc_stat_s
           structure (from ffio.h).  Fields in this structure are filled in
           as appropriate by the layers.  For the system call layer, all
           fields are simply retrieved by doing an fstat call.  For other
           layers, such as mr, the size field in the stat structure is
           modified to reflect the buffered data.  Other layers can make
           similar changes to the basic information from the system for
           similar reasons.  The result is a stat structure that can be
           used in the same way and for the same purposes as the fstat
           system call.

RETURN VALUES
     The fffcntl function returns 0 on success.  Otherwise, it returns -1
     and the sw_error field of the stat structure contains the error
     number.

SEE ALSO
     fflistio(3C) ffopen(3C), ffreada(3C), ffsetsp(3C), ffwritea(3C)

     assign(1),