There are three types of input and output (I/O) in the Compaq C Run-Time Library (RTL): UNIX, Standard, and Terminal. Table 2-1 lists all the I/O functions and macros found in the Compaq C RTL. For more detailed information on each function and macro, see the Reference Section.

2.1 Using RMS from RTL Routines

When you create a file using the Compaq C RTL I/O functions and macros, you can supply values for many RMS file attributes, including:

• Allocation quantity
• Block size
• Default file extension
• Default file name
• File access context options
• File-processing options
• File-sharing options
• Multiblock count
• Multibuffer count
• Maximum record size
• Record attributes
• Record format
• Record-processing options

See the description of the creat function in the Reference Section for information on these values.

Other functions that allow you to set these values include open , fopen , and freopen .

For more information about RMS, see the Compaq C User's Guide for OpenVMS Systems.

2.2 UNIX I/O and Standard I/O

UNIX I/O functions are UNIX system services, now standardized by ISO POSIX-1 (the ISO Portable Operating System Interface).

UNIX I/O functions use file descriptors to access files. A file descriptor is an integer that identifies the file. A file descriptor is declared in the following way, where file_desc is the name of the file descriptor:

int  file_desc;

UNIX I/O functions, such as creat , associate the file descriptor with a file. Consider the following example:

file_desc1 = creat("INFILE.DAT", 0, "rat=cr", "rfm=var");

This statement creates the file, INFILE.DAT, with file access mode 0, carriage-return control, variable-length records, and it associates the variable file_desc1 with the file. When the file is accessed for other operations, such as reading or writing, the file descriptor is used to refer to the file. For example:

write(file_desc1, buffer, sizeof(buffer));

This statement writes the contents of the buffer to INFILE.DAT.

There may be circumstances when you should use UNIX I/O functions and macros instead of the Standard I/O functions and macros. For a detailed discussion of both forms of I/O and how they manipulate the RMS file formats, see Chapter 1.

Standard I/O functions are specified by the ANSI C Standard.

Standard I/O functions add buffering to the features of UNIX I/O and use file pointers to access files. A file pointer is an object of type FILE * , which is a typedef defined in the <stdio.h> header file as follows:

typedef  struct  _iobuf  *FILE;

The _iobuf identifier is also defined in <stdio.h> .

To declare a file pointer, use the following:

FILE  *file_ptr;

You use the Standard I/O fopen function to create or open an existing file. For example:

#include <stdio.h>

main()
{
   FILE  *outfile;
   outfile  =  fopen("DISKFILE.DAT", "w+");
      .
      .
      .
}

Here, the file DISKFILE.DAT is opened for write-update access.

The Compaq C RTL provides the following functions for converting between file descriptors and file pointers:

• fileno ---returns the file descriptor associated with the specified file pointer.
• fdopen ---associates a file pointer with a file descriptor returned by an open , creat , dup , dup2 , or pipe function.

2.3 Wide-Character Versus Byte I/O Functions

The wide-character I/O functions provide operations analogous to most of the byte I/O functions, except that the fundamental units internal to the wide-character functions are wide characters.

However, the external representation (in files) is a sequence of multibyte characters, not wide characters. For the wide-character formatted input and output functions:

• The wide-character formatted input functions (such as fwscanf ) always read a sequence of multibyte characters from files, regardless of the specified directive and, before any further processing, convert this sequence to a sequence of wide characters.
• The wide-character formatted output functions (such as fwprintf ) write wide characters to output files by first converting wide-character argument types to a sequence of multibyte characters, then calling the underlying operating system output primitives.

Byte I/O functions cannot handle state-dependent encodings. Wide-character I/O functions can. They accomplish this by associating each wide-character stream with a conversion-state object of type mbstate_t .

The wide-character I/O functions are:

fgetwc        fputwc        fwscanf       fwprintf       ungetwc
fgetws        fputws        wscanf        wprintf
getwc         putwc                       vfwprintf
getwchar      putwchar                    vwprintf

The byte I/O functions are:

fgetc         fputc         fscanf        fprintf         ungetc
fgets         fputs         scanf         printf          fread
getc          putc                        vfprinf         fwrite
gets          puts                        vprintf
getchar       putchar

The wide-character input functions read multibyte characters from the stream and convert them to wide characters as if they were read by successive calls to the fgetwc function. Each conversion occurs as a call were made to the mbrtowc function with the conversion state described by the stream's own mbstate_t object.

The wide-character output functions convert wide characters to multibyte characters and write them to the stream as if they were written by successive calls to the fputwc function. Each conversion occurs as if a call were made to the wcrtomb function, with the conversion state described by the I/O stream's own mbstate_t object.

If a wide-character I/O function encounters an invalid multibyte character, the function sets errno to the value EILSEQ.

2.4 Conversion Specifications

Several of the Standard I/O functions (including the Terminal I/O functions) use conversion specifications to specify data formats for I/O. These functions are the formatted-input and formatted-output functions. Consider the following example:

int     x = 5.0;
FILE    *outfile;
   .
   .
   .
fprintf(outfile, "The answer is %d.\n", x);

The decimal value of the variable x replaces the conversion specification %d in the string to be written to the file associated with the identifier outfile.

Each conversion specification begins with a percent sign (%) and ends with a conversion specifier, which is a character that specifies the type of conversion to be performed. Optional characters can appear between the percent sign and the conversion specifier.

For the wide-character formatted I/O functions, the conversion specification is a string of wide characters. For the byte I/O equivalent functions, it is a string of bytes.

Sections 2.4.1 and 2.4.2 describe these optional characters and conversion specifiers.

2.4.1 Converting Input Information

The format specification string for the input of information can include three kinds of items:

• White-space characters (spaces, tabs, and new-line characters), which match optional white-space characters in the input field.
• Ordinary characters (not %), which must match the next nonwhite-space character in the input.
• Conversion specifications, which govern the conversion of the characters in an input field and their assignment to an object indicated by a corresponding input pointer.

Each input pointer is an address expression indicating an object whose type matches that of a corresponding conversion specification. Conversion specifications form part of the format string. The indicated object is the target that receives the input value. There must be as many input pointers as there are conversion specifications, and the addressed objects must match the types of the conversion specifications.

A conversion specification consists of the following characters, in the order listed:

• A percent character (%) or the sequence %n$ (where n is an integer),
  The sequence %n$ denotes that the conversion is applied to the nth input pointer listed, where n is a decimal integer between [1, NL_ARGMAX] (see the <limits.h> header file). For example, a conversion specification beginning %5$ means that the conversion will be applied to the 5th input pointer listed after the format specification. The sequence %$ is invalid.
  If the conversion specification does not begin with the sequence %n$, the conversion specification is matched to its input pointer in left-to-right order. You should only use one type of conversion specification (% or %n$) in a format specification.
• One or more optional characters (described in Table 2-2).
• A conversion specifier (described in Table 2-3).

Table 2-2 shows the characters you can use between the percent sign (%) (or the sequence %n$), and the conversion specifier. These characters are optional but, if specified, must occur in the order shown in Table 2-2.

%lc, %ls, %C, %S, %[

Table 2-3 describes the conversion specifiers for formatted input.