HP C
Run-Time Library Reference Manual for OpenVMS Systems

The normal interface to the function (2) is declared using the pointer size specified on the /POINTER_SIZE qualifier. Because the header file is in 64-bit pointer context and because of the statements at (1), the declaration at (2) is made using the same pointer-size context as the /POINTER_SIZE qualifier.

The 32-bit specific interface (3) and the 64-bit specific interface (4) are declared in 32-bit and 64-bit pointer-size context, respectively.

Chapter 2
Understanding Input and Output

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

Table 2-1 I/O Functions and Macros
Function or Macro Description

UNIX I/O---Opening and Closing Files

close Closes the file associated with a file descriptor.

creat Creates a new file.

dup, dup2 Allocates a new descriptor that refers to a file specified by a file descriptor returned by open , creat , or pipe .

open Opens a file and positions it at its beginning.

UNIX I/O---Reading from Files

read Reads bytes from a file and places them in a buffer.

UNIX I/O---Writing to Files

write Writes a specified number of bytes from a buffer to a file.

UNIX I/O---Maneuvering in Files

lseek Positions a stream file to an arbitrary byte position and returns the new position as an int .

UNIX I/O---Additional X/Open I/O Functions and Macros

fstat, stat Accesses information about the file descriptor or the file specification.

flockfile, ftrylockfile, funlockfile File-pointer-locking functions.

fsync Writes to disk any buffered information for the specified file.

getname Returns the file specification associated with a file descriptor.

isapipe Returns 1 if the file descriptor is associated with a pipe and 0 if it is not.

isatty Returns 1 if the specified file descriptor is associated with a terminal and 0 if it is not.

lwait Waits for completion of pending asynchronous I/O.

ttyname Returns a pointer to the null-terminated name of the terminal device associated with file descriptor 0, the default input device.

Standard I/O---Opening and Closing Files

fclose Closes a function by flushing any buffers associated with the file control block, and freeing the file control block and buffers previously associated with the file pointer.

fdopen Associates a file pointer with a file descriptor returned by an open , creat , dup , dup2 , or pipe function.

fopen Opens a file by returning the address of a FILE structure.

freopen Substitutes the file, named by a file specification, for the open file addressed by a file pointer.

Standard I/O---Reading from Files

fgetc, getc, fgetwc, getw, getwc Returns characters from a specified file.

fgets, fgetws Reads a line from a specified file and stores the string in an argument.

fread Reads a specified number of items from a file.

fscanf, fwscanf, vfscanf, vfwscanf Performs formatted input from a specified file.

sscanf, swscanf, vsscanf, vswscanf Performs formatted input from a character string in memory.

ungetc, ungetwc Pushes back a character into the input stream and leaves the stream positioned before the character.

Standard I/O---Writing to Files

fprintf, fwprintf, vfprintf, vfwprintf Performs formatted output to a specified file.

fputc, putc, putw, putwc, fputwc Writes characters to a specified file.

fputs, fputws Writes a character string to a file without copying the string's null terminator.

fwrite Writes a specified number of items to a file.

sprintf, swprintf, vsprintf, vswprintf Performs formatted output to a string in memory.

Standard I/O---Maneuvering in Files

fflush Sends any buffered information for the specified file to RMS.

fgetpos Stores the current value of the file position indicator for the stream.

fsetpos Sets the file position indicator for the stream according to the value of the object pointed to.

fseek , fseeko Positions the file to the specified byte offset in the file.

ftell , ftello Returns the current byte offset to the specified stream file.

rewind Sets the file to its beginning.

Standard I/O---Additional Standard I/O Functions and Macros

access Checks a file to see whether a specified access mode is allowed.

clearerr Resets the error and end-of-file indications for a file.

feof Tests a file to see if the end-of-file has been reached.

ferror Returns a nonzero integer if an error has occurred while reading or writing a file.

fgetname Returns the file specification associated with a file pointer.

fileno Returns an integer file descriptor that identifies the specified file.

ftruncate Truncates a file at the specified position.

fwait Waits for completion of pending asynchcronous I/O.

fwide Sets the orientation a stream.

mktemp Creates a unique filename from a template.

remove, delete Deletes a file.

rename Gives a new name to an existing file.

setbuf, setvbuf Associates a buffer with an input or output file.

tmpfile Creates a temporary file that is opened for update.

tmpnam Creates a character string that can be used in place of the file-name argument in other function calls.

Terminal I/O---Reading from Files

getchar, getwchar Reads a single character from the standard input ( stdin ).

gets Reads a line from the standard input ( stdin ).

scanf, wscanf, vscanf, vwscanf Performs formatted input from the standard input.

Terminal I/O---Writing to Files

printf, wprintf, vprintf, vwprintf Performs formatted output to the standard output ( stdout ).

putchar, putwchar Writes a single character to the standard output and returns the character.

puts Writes a character string to the standard output followed by a new-line character.

**Table 2-1 I/O Functions and Macros**
Function or Macro	Description
UNIX I/O---Opening and Closing Files
`close`	Closes the file associated with a file descriptor.
`creat`	Creates a new file.
`dup, dup2`	Allocates a new descriptor that refers to a file specified by a file descriptor returned by `open` , `creat` , or `pipe` .
`open`	Opens a file and positions it at its beginning.
UNIX I/O---Reading from Files
`read`	Reads bytes from a file and places them in a buffer.
UNIX I/O---Writing to Files
`write`	Writes a specified number of bytes from a buffer to a file.
UNIX I/O---Maneuvering in Files
`lseek`	Positions a stream file to an arbitrary byte position and returns the new position as an `int` .
UNIX I/O---Additional X/Open I/O Functions and Macros
`fstat, stat`	Accesses information about the file descriptor or the file specification.
`flockfile, ftrylockfile, funlockfile`	File-pointer-locking functions.
`fsync`	Writes to disk any buffered information for the specified file.
`getname`	Returns the file specification associated with a file descriptor.
`isapipe`	Returns 1 if the file descriptor is associated with a pipe and 0 if it is not.
`isatty`	Returns 1 if the specified file descriptor is associated with a terminal and 0 if it is not.
`lwait`	Waits for completion of pending asynchronous I/O.
`ttyname`	Returns a pointer to the null-terminated name of the terminal device associated with file descriptor 0, the default input device.
Standard I/O---Opening and Closing Files
`fclose`	Closes a function by flushing any buffers associated with the file control block, and freeing the file control block and buffers previously associated with the file pointer.
`fdopen`	Associates a file pointer with a file descriptor returned by an `open` , `creat` , `dup` , `dup2` , or `pipe` function.
`fopen`	Opens a file by returning the address of a FILE structure.
`freopen`	Substitutes the file, named by a file specification, for the open file addressed by a file pointer.
Standard I/O---Reading from Files
`fgetc, getc, fgetwc, getw, getwc`	Returns characters from a specified file.
`fgets, fgetws`	Reads a line from a specified file and stores the string in an argument.
`fread`	Reads a specified number of items from a file.
`fscanf, fwscanf, vfscanf, vfwscanf`	Performs formatted input from a specified file.
`sscanf, swscanf, vsscanf, vswscanf`	Performs formatted input from a character string in memory.
`ungetc, ungetwc`	Pushes back a character into the input stream and leaves the stream positioned before the character.
Standard I/O---Writing to Files
`fprintf, fwprintf, vfprintf, vfwprintf`	Performs formatted output to a specified file.
`fputc, putc, putw, putwc, fputwc`	Writes characters to a specified file.
`fputs, fputws`	Writes a character string to a file without copying the string's null terminator.
`fwrite`	Writes a specified number of items to a file.
`sprintf, swprintf, vsprintf, vswprintf`	Performs formatted output to a string in memory.
Standard I/O---Maneuvering in Files
`fflush`	Sends any buffered information for the specified file to RMS.
`fgetpos`	Stores the current value of the file position indicator for the stream.
`fsetpos`	Sets the file position indicator for the stream according to the value of the object pointed to.
`fseek` , `fseeko`	Positions the file to the specified byte offset in the file.
`ftell` , `ftello`	Returns the current byte offset to the specified stream file.
`rewind`	Sets the file to its beginning.
Standard I/O---Additional Standard I/O Functions and Macros
`access`	Checks a file to see whether a specified access mode is allowed.
`clearerr`	Resets the error and end-of-file indications for a file.
`feof`	Tests a file to see if the end-of-file has been reached.
`ferror`	Returns a nonzero integer if an error has occurred while reading or writing a file.
`fgetname`	Returns the file specification associated with a file pointer.
`fileno`	Returns an integer file descriptor that identifies the specified file.
`ftruncate`	Truncates a file at the specified position.
`fwait`	Waits for completion of pending asynchcronous I/O.
`fwide`	Sets the orientation a stream.
`mktemp`	Creates a unique filename from a template.
`remove, delete`	Deletes a file.
`rename`	Gives a new name to an existing file.
`setbuf, setvbuf`	Associates a buffer with an input or output file.
`tmpfile`	Creates a temporary file that is opened for update.
`tmpnam`	Creates a character string that can be used in place of the file-name argument in other function calls.
Terminal I/O---Reading from Files
`getchar, getwchar`	Reads a single character from the standard input ( `stdin` ).
`gets`	Reads a line from the standard input ( `stdin` ).
`scanf, wscanf, vscanf, vwscanf`	Performs formatted input from the standard input.
Terminal I/O---Writing to Files
`printf, wprintf, vprintf, vwprintf`	Performs formatted output to the standard output ( `stdout` ).
`putchar, putwchar`	Writes a single character to the standard output and returns the character.
`puts`	Writes a character string to the standard output followed by a new-line character.

2.1 Using RMS from RTL Routines

When you create a file using the HP 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 filename
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 HP 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;

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 HP 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 similar 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 if 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 with %5$ means that the conversion will be applied to the fifth 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 (see Table 2-2).
A conversion specifier (see 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.

Table 2-2 Optional Characters Between% (or% n$) and the Input Conversion Specifier
Character Meaning

* An assignment-suppressing character.

field width A nonzero decimal integer that specifies the maximum field width.
For the wide-character input functions, the field width is measured in wide characters.
For the byte input functions, the field width is measured in bytes, unless the directive is one of the following:
%lc, %ls, %C, %S, %[

In these cases, the field width is measured in multibyte character units.
For programs compiled with / L_DOUBLE=64 (that is, compiled without the default /L_DOUBLE=128), the maximum field width is 1024.

h, l, or L (or ll) Precede a conversion specifier of d, i, or n with an h if the corresponding argument is a pointer to short int rather than a pointer to int ; with an l (lowercase ell) if it is a pointer to long int ; or, for OpenVMS Alpha systems only, with an L or ll (two lowercase ells) if it is a pointer to __int64 .
Precede a conversion specifier of o, u, or x with an h if the corresponding argument is a pointer to unsigned short int rather than a pointer to unsigned int ; with an l if it is a pointer to unsigned long int ; or, for OpenVMS Alpha systems only, with an L or ll if it is a pointer to unsigned __int64 .
Precede a conversion specifier of c, s, or [ with an l (lowercase ell) if the corresponding argument is a pointer to a wchar_t .
Finally, precede a conversion specifier of e, f, or g with an l (lowercase ell) if the corresponding argument is a pointer to double rather than a pointer to float , or with an L if it is a pointer to long double .
If an h, l, L, or ll appears with any other conversion specifier, then the behavior is undefined.

**Table 2-2 Optional Characters Between% (or% n$) and the Input Conversion Specifier**
Character	Meaning
*	An assignment-suppressing character.
field width	A nonzero decimal integer that specifies the maximum field width. For the wide-character input functions, the field width is measured in wide characters. For the byte input functions, the field width is measured in bytes, unless the directive is one of the following: %lc, %ls, %C, %S, %[ In these cases, the field width is measured in multibyte character units. For programs compiled with / L_DOUBLE=64 (that is, compiled without the default /L_DOUBLE=128), the maximum field width is 1024.
h, l, or L (or ll)	Precede a conversion specifier of d, i, or n with an h if the corresponding argument is a pointer to `short int` rather than a pointer to `int` ; with an l (lowercase ell) if it is a pointer to `long int` ; or, for OpenVMS Alpha systems only, with an L or ll (two lowercase ells) if it is a pointer to `__int64` . Precede a conversion specifier of o, u, or x with an h if the corresponding argument is a pointer to `unsigned short int` rather than a pointer to `unsigned int` ; with an l if it is a pointer to `unsigned long int` ; or, for OpenVMS Alpha systems only, with an L or ll if it is a pointer to `unsigned __int64` . Precede a conversion specifier of c, s, or [ with an l (lowercase ell) if the corresponding argument is a pointer to a `wchar_t` . Finally, precede a conversion specifier of e, f, or g with an l (lowercase ell) if the corresponding argument is a pointer to `double` rather than a pointer to `float` , or with an L if it is a pointer to `long double` . If an h, l, L, or ll appears with any other conversion specifier, then the behavior is undefined.

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

Table 2-3 Conversion Specifiers for Formatted Input
Specifier Input Type¹ Description

d Expects a decimal integer in the input whose format is the same as expected for the subject sequence of the strtol function with the value 10 for the base argument. The corresponding argument must be a pointer to int .

i Expects an integer whose type is determined by the leading input characters. A leading 0 is equated to octal, a leading 0X or 0x is equated to hexadecimal, and all other forms are equated to decimal. The corresponding argument must be a pointer to int .

o Expects an octal integer in the input (with or without a leading 0). The corresponding argument must be a pointer to int .

u Expects a decimal integer in the input whose format is the same as expected for the subject sequence of the strtoul function with the value 10 for the base argument.

x Expects a hexadecimal integer in the input (with or without a leading 0x). The corresponding argument must be a pointer to unsigned int .

c Byte Expects a single byte in the input. The corresponding argument must be a pointer to char .
If a field width precedes the c conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of char .
If the optional character l (lowercase ell) precedes this conversion specifier, then the specifier expects a multibyte character in the input which is converted into a wide-character code.
The corresponding argument must be a pointer to type wchar_t . If a field width also precedes the c conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of wchar_t .

Wide-character Expects a sequence of the number of characters specified in the optional field width; this is 1 if not specified.
If no l (lowercase ell) precedes the c specifier, then the corresponding argument must be a pointer to an array of char .
If an l (lowercase ell) precedes the c specifier, then the corresponding argument must be a pointer to an array of wchar_t .

C Byte The specifier expects a multibyte character in the input, which is converted into a wide-character code. The corresponding argument must be a pointer to type wchar_t .
If a field width also precedes the C conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of wchar_t .

Wide-character Expects a sequence of the number of characters specified in the optional field width; this is 1 if not specified. The corresponding argument must be a pointer to an array of wchar_t .

s Byte Expects a sequences of bytes in the input. The corresponding argument must be a pointer to an array of characters that is large enough to contain the sequence and a terminating null character (\0) that is automatically added. The input field is terminated by a space, tab, or new-line character.
If the optional character l (ell) precedes this conversion specifier, then the specifier expects a sequence of multibyte characters in the input, which are converted to wide-character codes. The corresponding argument must be a pointer to an array of wide characters (type wchar_t ) that is large enough to contain the sequence plus the terminating null wide-character code that is automatically added. The input field is terminated by a space, tab, or new-line character.

Wide-character Expects (conceptually) a sequence of nonwhite-space characters in the input.
If no l (lowercase ell) precedes the s specifier, then the corresponding argument must be a pointer to an array of char large enough to contain the sequence plus the terminating null byte that is automatically added.
If an l (lowercase ell) precedes the s specifier, then the corresponding argument must be a pointer to an array of wchar_t large enough to contain the sequence plus the terminating null wide character that is automatically added.

S Byte The specifier expects a sequence of multibyte characters in the input, which are converted to wide-character codes. The corresponding argument must be a pointer to an array of wide characters (type wchar_t ) that is large enough to contain the sequence plus a terminating null wide-character code that is added automatically. The input field is terminated by a space, tab, or new-line character.

Wide-character Expects a sequence of nonwhite-space characters in the input. The corresponding argument must be a pointer to an array of wchar_t large enough to contain the sequence plus the terminating null wide character that is automatically added.

e, f, g Expects a floating-point number in the input. The corresponding argument must be a pointer to float . The input format for floating-point numbers is: [±]nnn[radix][ddd][{E|e}[±]nn]. The n's and d's are decimal digits (as many as indicated by the field width minus the signs and the letter E). The radix character is defined in the current locale.

[...] Expects a nonempty sequence of characters that is not delimited by a white-space character. The brackets enclose a set of characters (the scanset) expected in the input sequence. Any character in the input sequence that does not match a character in the scanset terminates the character sequence.
All characters between the brackets comprise the scanset, unless the first character after the left bracket is a circumflex (^). In this case, the scanset contains all characters other than those that appear between the circumflex and the right bracket. Any character that does appear between the circumflex and the right bracket will terminate the input character sequence.
If the conversion specifier begins with [] or [^], then the right bracket character is in the scanset and the next right bracket character is the matching right bracket that ends the specification; otherwise, the first right bracket character ends the specification.

Byte If an l (lowercase ell) does not precede the [ specifier, then the characters in the scanset must be single-byte characters only. In this case, the corresponding argument must be a pointer to an array of char large enough to accept the sequence and the terminating null byte that is automatically added.
If an l (lowercase ell) does precede the [ specifier, then the characters in the input sequence are considered to be multibyte characters, which are then converted to a wide-character sequence for further processing. If character ranges are specified in the scanset, then the processing is done according to the LC_COLLATE category of the current program's locale. In this case, the corresponding argument must be a pointer to an array of wchar_t large enough to accept the sequence and the terminating null wide character that is automatically added.

Wide-character If no l (lowercase ell) precedes the [ conversion specifier, then processing is the same as described for the byte-input type of the %l[ specifier, except that the corresponding argument must be an array of char large enough to accept the multibyte sequence plus the terminating null byte that is automatically added.
If an l (lowercase ell) precedes the [ conversion specifier, then processing is the same as in the preceding paragraph except that the corresponding argument must be an array of wchar_t large enough to accept the wide-character sequence plus the terminating null wide character that is automatically added.

p Requires an argument that is a pointer to void . The input value is interpreted as a hexadecimal value.

n No input is consumed. The corresponding argument is a pointer to an integer. The integer is assigned the number of characters read from the input stream so far by this call to the formatted input function. Execution of a %n directive does not increment the assignment count returned when the formatted input function completes execution.

% Matches a single percent symbol. No conversion or assignment takes place. The complete conversion specification would be %%.

**Table 2-3 Conversion Specifiers for Formatted Input**
Specifier	Input Type¹	Description
d		Expects a decimal integer in the input whose format is the same as expected for the subject sequence of the `strtol` function with the value 10 for the `base` argument. The corresponding argument must be a pointer to `int` .
i		Expects an integer whose type is determined by the leading input characters. A leading 0 is equated to octal, a leading 0X or 0x is equated to hexadecimal, and all other forms are equated to decimal. The corresponding argument must be a pointer to `int` .
o		Expects an octal integer in the input (with or without a leading 0). The corresponding argument must be a pointer to `int` .
u		Expects a decimal integer in the input whose format is the same as expected for the subject sequence of the `strtoul` function with the value 10 for the `base` argument.
x		Expects a hexadecimal integer in the input (with or without a leading 0x). The corresponding argument must be a pointer to `unsigned int` .
c	Byte	Expects a single byte in the input. The corresponding argument must be a pointer to `char` . If a field width precedes the c conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of `char` . If the optional character l (lowercase ell) precedes this conversion specifier, then the specifier expects a multibyte character in the input which is converted into a wide-character code. The corresponding argument must be a pointer to type `wchar_t` . If a field width also precedes the c conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of `wchar_t` .
	Wide-character	Expects a sequence of the number of characters specified in the optional field width; this is 1 if not specified. If no l (lowercase ell) precedes the c specifier, then the corresponding argument must be a pointer to an array of `char` . If an l (lowercase ell) precedes the c specifier, then the corresponding argument must be a pointer to an array of `wchar_t` .
C	Byte	The specifier expects a multibyte character in the input, which is converted into a wide-character code. The corresponding argument must be a pointer to type `wchar_t` . If a field width also precedes the C conversion specifier, then the number of characters specified by the field width is read. In this case, the corresponding argument must be a pointer to an array of `wchar_t` .
	Wide-character	Expects a sequence of the number of characters specified in the optional field width; this is 1 if not specified. The corresponding argument must be a pointer to an array of `wchar_t` .
s	Byte	Expects a sequences of bytes in the input. The corresponding argument must be a pointer to an array of characters that is large enough to contain the sequence and a terminating null character (\0) that is automatically added. The input field is terminated by a space, tab, or new-line character. If the optional character l (ell) precedes this conversion specifier, then the specifier expects a sequence of multibyte characters in the input, which are converted to wide-character codes. The corresponding argument must be a pointer to an array of wide characters (type `wchar_t` ) that is large enough to contain the sequence plus the terminating null wide-character code that is automatically added. The input field is terminated by a space, tab, or new-line character.
	Wide-character	Expects (conceptually) a sequence of nonwhite-space characters in the input. If no l (lowercase ell) precedes the s specifier, then the corresponding argument must be a pointer to an array of `char` large enough to contain the sequence plus the terminating null byte that is automatically added. If an l (lowercase ell) precedes the s specifier, then the corresponding argument must be a pointer to an array of `wchar_t` large enough to contain the sequence plus the terminating null wide character that is automatically added.
S	Byte	The specifier expects a sequence of multibyte characters in the input, which are converted to wide-character codes. The corresponding argument must be a pointer to an array of wide characters (type `wchar_t` ) that is large enough to contain the sequence plus a terminating null wide-character code that is added automatically. The input field is terminated by a space, tab, or new-line character.
	Wide-character	Expects a sequence of nonwhite-space characters in the input. The corresponding argument must be a pointer to an array of `wchar_t` large enough to contain the sequence plus the terminating null wide character that is automatically added.
e, f, g		Expects a floating-point number in the input. The corresponding argument must be a pointer to `float` . The input format for floating-point numbers is: [±]nnn[radix][ddd][{E\|e}[±]nn]. The n's and d's are decimal digits (as many as indicated by the field width minus the signs and the letter E). The radix character is defined in the current locale.
[...]		Expects a nonempty sequence of characters that is not delimited by a white-space character. The brackets enclose a set of characters (the scanset) expected in the input sequence. Any character in the input sequence that does not match a character in the scanset terminates the character sequence. All characters between the brackets comprise the scanset, unless the first character after the left bracket is a circumflex (^). In this case, the scanset contains all characters other than those that appear between the circumflex and the right bracket. Any character that does appear between the circumflex and the right bracket will terminate the input character sequence. If the conversion specifier begins with [] or [^], then the right bracket character is in the scanset and the next right bracket character is the matching right bracket that ends the specification; otherwise, the first right bracket character ends the specification.
	Byte	If an l (lowercase ell) does not precede the [ specifier, then the characters in the scanset must be single-byte characters only. In this case, the corresponding argument must be a pointer to an array of `char` large enough to accept the sequence and the terminating null byte that is automatically added. If an l (lowercase ell) does precede the [ specifier, then the characters in the input sequence are considered to be multibyte characters, which are then converted to a wide-character sequence for further processing. If character ranges are specified in the scanset, then the processing is done according to the LC_COLLATE category of the current program's locale. In this case, the corresponding argument must be a pointer to an array of `wchar_t` large enough to accept the sequence and the terminating null wide character that is automatically added.
	Wide-character	If no l (lowercase ell) precedes the [ conversion specifier, then processing is the same as described for the byte-input type of the %l[ specifier, except that the corresponding argument must be an array of `char` large enough to accept the multibyte sequence plus the terminating null byte that is automatically added. If an l (lowercase ell) precedes the [ conversion specifier, then processing is the same as in the preceding paragraph except that the corresponding argument must be an array of `wchar_t` large enough to accept the wide-character sequence plus the terminating null wide character that is automatically added.
p		Requires an argument that is a pointer to `void` . The input value is interpreted as a hexadecimal value.
n		No input is consumed. The corresponding argument is a pointer to an integer. The integer is assigned the number of characters read from the input stream so far by this call to the formatted input function. Execution of a %n directive does not increment the assignment count returned when the formatted input function completes execution.
%		Matches a single percent symbol. No conversion or assignment takes place. The complete conversion specification would be %%.

¹Either byte or wide-character. Where neither is shown for a given specifier, the specifier description applies to both.

Contents

Index

HP CRun-Time Library Reference Manual for OpenVMS Systems