afwrite

afwrite

Write a Record

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
DIAGNOSTICS
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lcio.h>

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

DESCRIPTION

afwrite writes items to the stream associated with the FILE object addressed by f and then forces a record break. size defines the size of each item, count defines the number of items to be written, and ptr addresses the area containing the items. If all the items do not fit into the current record, a diagnostic message is generated, and the file's error flag is set.

Calls to afwrite to write items of type typeval commonly have this form:

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

afwrite is supported only for binary streams. See Augmented Standard I/O for more information.

RETURN VALUE

afwrite returns the number of items written. If there are too many items, only those that fit are written.

CAUTION

When used on a file with relative attributes, afwrite behaves exactly like fwrite because such a file is 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 you call afwrite with a size or count of 0, nothing is written. You must use the afwrite0 function to write a zero-length record.

DIAGNOSTICS

afwrite never writes more than a single record; it is an error if there is no room in the current record for all items.

The return value from afwrite does not indicate whether the call is completely successful. You can use the ferror function to determine whether an error occurs.

EXAMPLE

This program writes out the same data three different ways using fputs , fwrite , and afwrite . This example illustrates the different ways that these functions handle new lines and record boundaries:

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

main()
{
   FILE *f1, *f2, *f3;
   char *strings[] = {
      "a\nb", "a\nb\nc", "a\nb\nc\nd", "a\nb\nc\nd\ne",
      "a\nb\nc\nd\ne\nf" };
   int i;
      /* Open for text when we use fputs.                         */
   f1 = afopen("cms:fputs output", "w", "", "recfm=v,reclen=20");
   f2 = afopen("cms:fwrite output", "wb", "", "recfm=v,reclen=20");
      /* Open for binary when we use fwrite or afwrite.           */
   f3 = afopen("cms:afwrite output", "wb", "", "recfm=v,reclen=20");


   if (!f1 || !f2 || !f3){
         puts("File(s) failed to open.");
         exit(EXIT_FAILURE);
   }
   for (i = 0; i < sizeof(strings)/sizeof(strings[0]); ++i){
         fputs(strings[i], f1);
         fwrite(strings[i], strlen(strings[i]), 1, f2);
         afwrite(strings[i], strlen(strings[i]), 1, f3);
   }
   fclose(f1); fclose(f2); fclose(f3);
   puts("Compare output files: FPUTS OUTPUT, FWRITE OUTPUT and "
          "AFWRITE OUTPUT.");
   exit(EXIT_SUCCESS);
}

RELATED FUNCTIONS

afwrite0 , afwriteh , kinsert , kreplace , fputs