ffopen(3C)

NAME
     ffopen, ffopens, ffclose, ffopenf, ffclosef - Opens or closes a file
     using flexible file I/O

SYNOPSIS
     #include <fcntl.h>
     #include <ffio.h>

     UNICOS and UNICOS/mk systems:

        int ffopen (const char *name, int oflag [, int mode
        [, long cbits [, struct ffsw *stat]]]);

        int ffopens (const char *name, int oflag, int mode,
        long cbits, [int cblks,] struct ffsw *stat, const char *str);

        ffclose (int fd [, struct ffsw *stat]);

     IRIX systems:

        int ffopen (const char *name, int oflag [,mode_t mode]);

        int ffopens (const char *name, int oflag, mode_t mode,
        long cbits, int cblks, struct ffsw *stat, const char *str);

        int ffclose (int fd);

     All systems:

        ffclosef (int fd, struct ffsw *stat);

        int ffopenf (const char *name, int oflag , int ,mode_t mode long
        cbits, int cblks, struct ffsw *stat);

IMPLEMENTATION
     UNICOS, UNICOS/mk, and IRIX systems

DESCRIPTION
     The ffopen and ffopens functions open a file using flexible file I/O
     (FFIO).  These functions are modeled after the open(2) system call.
     The file associated with name is opened, and appropriate structures
     are built to do special handling on the file.  For ffopen, the
     processing layers to be used are as requested with the asgcmd(1) or
     assign(1) commands.  For ffopens, the layers are specified by the
     string at str.

     The ffopen function returns an integer.  Although it is not a file
     descriptor, it is used in much the same way when passed to the other
     functions such as ffread, ffwrite, or ffclose.

     The oflag, mode, and cbits parameters are exactly as in open(2).

     On IRIX systems, the cbits and cblks parameters are ignored.

     The stat parameter is a pointer to a status return structure
     containing a flag, an error indication, a transfer count, and an
     indication of the condition that terminated the request.

     The ffclose and ffclosef functions close the file associated with fd.
     It does any necessary flushing and termination for that file.  Files
     opened using ffopen(3C) are not guaranteed to be flushed at program
     termination; call ffclose or ffclosef to ensure this.

NOTES
     On IRIX systems, the FFIO routines are stored in libffio.so, and are
     available in the N32 and N64 ABIs.

RETURN VALUES
     Upon successful completion, a non-negative integer is returned; this
     integer is currently a pointer to a control block.  Otherwise, -1 is
     returned, and, if the stat parameter is passed, the error value is
     found in stat.sw_error.  If the stat parameter is not provided, the
     error code is found in errno.  The stat parameter is required for
     ffopens() and ffclosef.

EXAMPLES
     To write a C program that will read the records of a COS blocked file
     named indata and copy the data from the file (without blocking
     information) to stdout, compile the following program:

          #include <stdio.h>
          #include <fcntl.h>
          #include <ffio.h>

          #define BSZ 10000

          main()
          {
                int fd, ret;
                char buf[BSZ];
                struct ffsw stat;
                int ubc = 0;

                fd = ffopen("indata", O_RDONLY);
                do
                {
                      ret = ffreadf(fd, buf, BSZ, &stat, PARTIAL, &ubc);
                      fwrite(buf, 1, ret, stdout);
                 } while (FFSTAT(stat) != FFEOD);
                 ret = ffclose(fd);
          }

     Use the following commands to compile, link, and run this program on
     UNICOS and UNICOS/mk systems:

          $ cc cpy.c
          $ eval `assign -F cos indata` # declare "indata" is COS blocked
          $ a.out

     Use the following commands to compile, link, and run this program on
     IRIX systems:

          $ cc cpy.c -lffio
          $ eval `assign -F cos indata` # declare "indata" is COS blocked
          $ a.out

     The same example program could be written to use the ffopens entry
     point.  The layers to use in decoding the blocking information are
     specified in the call, and not in the shell command asgcmd(1), as
     follows:

          #include <stdio.h>
          #include <fcntl.h>
          #include <ffio.h>

          #define BSZ 10000

          main()
          {
                int fd, ret;
                char buf[BSZ];
                char *str;
                struct ffsw stat;
                int ubc = 0;

                /* Set up to process COS blocked file. */
                str = "cos";
                fd = ffopens("indata", O_RDONLY, 0, 0L, 0, &stat, str);
                do
                {
                      ret = ffreadf(fd, buf, BSZ, &stat, PARTIAL, &ubc);
                      fwrite(buf, 1, ret, stdout);
                } while (FFSTAT(stat) != FFEOD);
                ret = ffclose(fd);
          }

     Use the following commands on UNICOS and UNICOS/mk systems to compile,
     link, and run this program:

          $ cc cpy.c
          $ a.out

     Use the following commands on IRIX systems to compile, link, and run
     this program:

          $ cc cpy.c -lffio

SEE ALSO
     ffread(3C), ffseek(3C)

     asgcmd(1)

     open(2) in the UNICOS System Calls Reference Manual, publication
     SR-2012

     Application Programmer's I/O Guide, publication SG-2168

     Application Programmer's Library Reference Manual, publication
     SR-2165, for the printed version of this man page.