SAS/C Library Reference, Vol. 1

afread -- Read a Record

SYNOPSIS

 #include <lcio.h>

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

DESCRIPTION

afread 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.

Calls to afread to obtain items of type typeval commonly have this form:

 typeval buf[count];
 afread(buf, sizeof(typeval), count, f);

afread 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 afread.

RETURN VALUE

afread returns the number of items read from the record (which may be less than the maximum).

CAUTION

When used on a file with relative attributes, afread behaves exactly like fread because these files are processed as a continuous stream 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.

If afread reads a zero-length record, it skips it and ignores it. Use the afread0 function if you are processing a file that may contain zero-length records.

DIAGNOSTICS

afread 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 afread does not indicate whether the call was completely successful. You can use the ferror function to determine whether an error occurred.

EXAMPLE

This example copies a single record from one file to another.

  #include <stdio.h>

  main()
  {
     FILE *input, *output;
     char buf[500];
     int len;

        /* Open file with undefined length records.   */
     input = afopen("tso:INPUT", "rb", "seq",
                    "recfm=u, reclen=50");
     output = afopen("tso:WRITE", "wb","seq", "");

        /* Read a record--len contains record length. */
     len = afread(buf, 1, 50, input);

     afwrite(buf, 1, len, output);

     fclose(input);
     fclose(output);
  }

RELATED FUNCTIONS

afread0, afreadh, fgets, kretrv