SAS/C Library Reference, Vol. 1

afread0 -- Read a Record (Possibly Length 0)

SYNOPSIS

 #include <lcio.h>

 int afread0(void *ptr, size_t size, size_t count, FILE *f);

DESCRIPTION

afread0 reads items from the stream associated with the FILE object addressed by f until a record break is encountered. size defines the size of each item, count defines the maximum number of items to be read, and ptr addresses the area into which the items will be read. If the current record contains more than count items, a diagnostic message is generated and the file's error flag is set. A zero-length record is considered to be a valid record containing 0 items.

Calls to afread0 to obtain items of type typeval commonly have the form

 typeval buf[count];
 numread = afread0(buf, sizeof(typeval), count, f);

afread0 is supported only for binary streams. You can use the fgets function to read a record from a text stream. See Augmented Standard I/O for more information on afread0.

Note: afread0 differs from afread only in the type of the return value and the treatment of zero-length records.

RETURN VALUE

afread0 returns the number of items read from the record (which may be less than the maximum or zero). If an error or end-of-file occurs, a negative value is returned.

CAUTION

When used on a file with relative attributes, afread0 behaves exactly like fread because these files are processed as continuous streams of characters without record boundaries. To process a file with relative attributes on a record-by-record basis, you must open it with afopen and specify the "seq" access method.

DIAGNOSTICS

afread0 never reads past the end of the current record; an error occurs if the record contains a fractional number of items or if it contains more data after count items.

The return value from afread0 does not distinguish between end of file and an error condition. Use the ferror function to make this distinction.

EXAMPLE

This example copies one file to another, preserving the record structure and including zero-length records. (It may not work on LRECL=X files because the record size for this kind of file is unbounded.) The input and output arguments are given as command line arguments.

  #include <lcio.h>
  #include <stdlib.h>

  char *_style = "tso";   /* Assume tso-style file names.         */

  main(int argc, char *argv[]) {
     FILE *in, *out;
     char *buf;           /* will be allocated to hold one record */
     int recsize;
     int count;
     int rc;
     if (argc < 3) {
        puts("Two arguments are required.");
        exit(EXIT_FAILURE);
     }
     if (argc > 3)
        puts("Extraneous command line arguments ignored.");
     in = fopen(argv[1], "rb");
     out = fopen(argv[2], "wb");
     if (!in || !out) {
        puts("File(s) failed to open.");
        exit(EXIT_FAILURE);
     }
        /* Get input file record size.   */
     recsize = fattr(in)->reclen;
        /* Guess if record size unknown. */
     if (recsize == 0) recsize = 65536;

        /* Allocate a buffer area.       */
     buf = malloc(recsize);
     if (buf == NULL) exit(EXIT_FAILURE);
     for(;;) {
           /* Read a record.     */
        count = afread0(buf, 1, recsize, in);
           /* EOF or input error */
        if (count < 0 || ferror(in)) break;
           /* Write the record.  */
        count = afwrite0(buf, 1, count, out);
           /* output error       */
        if (count < 0 || ferror(out)) break;
     }
     if (ferror(in) || ferror(out)) rc = EXIT_FAILURE;
     else rc = EXIT_SUCCESS;
     if (rc == EXIT_SUCCESS)
        puts("Copy was successful.");
     else puts("Copy failed (see library messages).");
     fclose(in);
     fclose(out);
     exit(rc);
  }

RELATED FUNCTIONS

afread