va_start_1, va_start

Used for initializing a variable to the beginning of the argument list.

Format

#include <varargs.h> (COMPAQ C EXTENSION)

void va_start (va_list ap);

void va_start_1 (va_list ap, int offset);

Arguments

ap

An object pointer. You must declare and use the argument ap as shown in the format section.

offset

The number of bytes by which ap is to be incremented so that it points to a subsequent argument within the list (that is, not to the start of the argument list). Using a nonzero offset can initialize ap to the address of the first of the optional arguments that follow a number of fixed arguments.

Description

The va_start macro initializes the variable ap to the beginning of the argument list.

The va_start_1 macro initializes ap to the address of an argument that is preceded by a known number of defined arguments. The printf function is an example of a Compaq C RTL function that contains a variable-length argument list offset from the beginning of the entire argument list. The variable-length argument list is offset by the address of the formatting string.

When determining value of the offset argument used in va_start_1 the implications of the OpenVMS calling standard must be considered.

On OpenVMS VAX, most argument items are a longword. For example, OpenVMS VAX arguments of types char and short use a full longword of memory when they are present in argument lists. However, OpenVMS VAX arguments of type float use two longwords because they are converted to type double .

On OpenVMS Alpha, each argument item is a quadword.

Note When accessing argument lists, especially those passed to a subroutine (written in C) by a program written in another programming language, consider the implications of the OpenVMS calling standard. For more information about the OpenVMS calling standard, see the Compaq C User's Guide for OpenVMS Systems or the OpenVMS Calling Standard.

The preceding version of va_start and va_start_1 is specific to the Compaq C RTL, and is not portable.

The following syntax describes the va_start macro in the <stdarg.h> header file, as defined in the ANSI C standard:

Format

#include <stdarg.h> (ANSI C)

void va_start (va_list ap, parmN);

Arguments

ap

An object pointer. You must declare and use the argument ap as shown in the format section.

parmN

The name of the last of the known fixed arguments.

Description

The pointer ap is initialized to point to the first of the optional arguments that follow parmN in the argument list.

Always use this version of va_start in conjunction with functions that are declared and defined with function prototypes. Also use this version of va_start to write portable programs.

For an example of argument-list processing using the <stdarg.h> functions and definitions, see Chapter 3, Example 3-6.

vfork

Creates an independent child process. This function is nonreentrant.

Format

#include <unistd.h>

int vfork (void); (_DECC_V4_SOURCE)

pid_t vfork (void); (NOT _DECC_V4_SOURCE)

Description

This function provided by Compaq C for OpenVMS Systems differs from the fork function provided by other C implementations. Table REF-12 shows the two major differences.

Table REF-12 The vfork and fork Functions

The vfork Function	The fork Function
Used with the exec functions.	Can be used without an exec function for asynchronous processing.
Creates an independent child process that shares some of the parent's characteristics.	Creates an exact duplicate of the parent process that branches at the point where vfork is called, as if the parent and the child are the same process at different stages of execution.

The vfork function provides the setup necessary for a subsequent call to an exec function. Although no process is created by vfork , it performs the following steps:

• It saves the return address (the address of the vfork call) to be used later as the return address for the call to an exec function.
• It saves the current context.
• It returns the integer 0 the first time it is called (before the call to an exec function is made). After the corresponding exec function call is made, the exec function returns control to the parent process, at the point of the vfork call, and it returns the process ID of the child as the return value. Unless the exec function fails, control appears to return twice from vfork even though one call was made to vfork and one call was made to the exec function.

The behavior of the vfork function is similar to the behavior of the setjmp function. Both vfork and setjmp establish a return address for later use, both return the integer 0 when they are first called to set up this address, and both pass back the second return value as though it were returned by them rather than by their corresponding exec or longjmp function calls.

However, unlike setjmp , with vfork , all local automatic variables, even those with volatile-qualified type, can have indeterminate values if they are modified between the call to vfork and the corresponding call to an exec routine.

Return Values

0	Indicates successful creation of the context.
nonzero	Indicates the process ID (PID) of the child process.
--1	Indicates an error -- failure to create the child process.

vfprintf

Prints formatted output based on an argument list.

Format

#include <stdio.h>

int vfprintf (FILE *file_ptr, const char *format, va_list arg);

Arguments

file_ptr

A pointer to the file to which the output is directed.

format

A pointer to a string containing the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Description

See the vprintf and vsprintf functions in this section.

See Chapter 2 for information on format specifiers.

Return Values

x	The number of bytes written.
Negative value	Indicates an output error. The function sets errno . For a list of possible errno values set, see fprintf in this section.

vfscanf

Reads formatted input based on an argument list.

Format

#include <stdio.h>

int vfscanf (FILE *file_ptr, const char *format, va_list arg);

Arguments

file_ptr

A pointer to the file that provides input text.

format

A pointer to a string containing the format specification.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Description

This function is the same as the fscanf function except that instead of being called with a variable number of arguments, it is called with an argument list that has been initialized by va_start (and possibly subsequent va_arg calls).

If no conversion specifications are given, you can omit the input pointers. Otherwise, the function calls must have exactly as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

For more information about format and conversion specifications and their corresponding arguments, see the "Understanding Input and Output" chapter of the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

This function returns the number of successfully matched and assigned input items.

Also see the vscanf and vsscanf functions in this section.

Return Values

n

The number of successfully matched and assigned input items.

EOF

Indicates that the end-of-file was encountered or a read error occurred. If a read error occurs, the function sets errno to one of the following: EILSEQ -- Invalid character detected. EINVAL -- Insufficient arguments. ENOMEM -- Not enough memory available for conversion. ERANGE -- Floating-point calculations overflow. EVMSERR -- Non-translatable VMS error. vaxc$errno contains the VMS error code. This can indicate that conversion to a numeric value failed due to overflow. The function can also set errno to the following as a result of errors returned from the I/O subsystem: EBADF -- The file descriptor is not valid. EIO -- I/O error. ENXIO -- Device does not exist. EPIPE -- Broken pipe. EVMSERR -- Non-translatable VMS error. vaxc$errno contains the VMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.

vfwprintf

Writes output to the stream under control of the wide-character format string.

Format

#include <wchar.h>

int vfwprintf (FILE *stream, const wchar_t *format, va_list arg);

Arguments

stream

A file pointer.

format

A pointer to a wide-character string containing the format specifications. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

arg

A variable list of the items needed for output.

Description

This function is equivalent to the fwprintf function, with the variable argument list replaced by the arg argument. Initialize arg with the va_start macro (and possibly with subsequent va_arg calls) from <stdarg.h> .

If the stream pointed to by stream has no orientation, vfwprintf makes the stream wide-oriented.

See also fwprintf in this section.

Return Values

n

The number of wide characters written.

Negative value

Indicates an error. The function sets errno to one of the following: EILSEQ -- Invalid character detected. EINVAL -- Insufficient arguments. ENOMEM -- Not enough memory available for conversion. ERANGE -- Floating-point calculations overflow. EVMSERR -- Nontranslatable VMS error. vaxc$errno contains the VMS error code. This might indicate that conversion to a numeric value failed because of overflow. The function can also set errno to the following as a result of errors returned from the I/O subsystem: EBADF -- The file descriptor is not valid. EIO -- I/O error. ENOSPC -- No free space on the device containing the file. ENXIO -- Device does not exist. EPIPE -- Broken pipe. ESPIPE -- Illegal seek in a file opened for append. EVMSERR -- Nontranslatable VMS error. vaxc$errno contains the VMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.

Examples

The following example shows the use of the vfwprintf function in a general error reporting routine.

#include <stdarg.h> #include <stdio.h> #include <wchar.h> void error(char *function_name, wchar_t *format, ...); { va_list args; va_start(args, format); /* print out name of function causing error */ fwprintf(stderr, L"ERROR in %s: ", function_name); /* print out remainder of message */ vfwprintf(stderr, format, args); va_end(args); }

vfwscanf

Reads input from the stream under control of a wide-character format string.

Format

#include <wchar.h>

int vfwscanf (FILE *stream, const wchar_t *format, va_list arg);

Arguments

stream

A file pointer.

format

A pointer to a wide-character string containing the format specifications.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Description

This function is equivalent to the fwscanf function, except that instead of being called with a variable number of arguments, it is called with an argument list (arg) that has been initialized by va_start (and possibly with subsequent va_arg calls).

If the stream pointed to by stream has no orientation, vfwscanf makes the stream wide-oriented.

For more information about format and conversion specifications and their corresponding arguments, see the "Understanding Input and Output" chapter of the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

Return Values

n	The number of successfully matched and assigned wide-character input items.
EOF	Indicates that a read error occurred before any conversion. The function sets errno . For a list of the values set by this function, see vfscanf in this section.

vprintf

Prints formatted output based on an argument list.

This function is the same as the printf function except that instead of being called with a variable number of arguments, it is called with an argument list that has been initialized by the va_start macro (and possibly with subsequent va_arg calls) from <stdarg.h> .

Format

#include <stdio.h>

int vprintf (const char *format, va_list arg);

Arguments

format

A pointer to the string containing the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

arg

A variable list of the items needed for output.

Description

See the vfprintf and vsprintf functions this section.

See Chapter 2 for information on format specifiers.

Return Values

x	The number of bytes written.
Negative value	Indicates an output error. The function sets errno . For a list of possible errno values set, see fprintf in this section.

vscanf

Reads formatted input based on an argument list.

Format

#include <stdio.h>

int vscanf (const char *format, va_list arg);

Arguments

format

A pointer to the string containing the format specification.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Description

This function is the same as the scanf function except that instead of being called with a variable number of arguments, it is called with an argument list (arg) that has been initialized by the va_start macro (and possibly with subsequent va_arg calls).

For more information about format and conversion specifications and their corresponding arguments, see the "Understanding Input and Output" chapter of the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

See the description of scanf in the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

Also see the vfscanf and vsscanf functions this section.

Return Values

n	The number of successfully matched and assigned input items.
EOF	Indicates that a read error occurred before any conversion. The function sets errno . For a list of the values set by this function, see vfscanf in this section.

vsprintf

Prints formatted output based on an argument list.

This function is the same as the sprintf function except that instead of being called with a variable number of arguments, it is called with an argument list that has been initialized by va_start (and possibly with subsequent va_arg calls).

Format

#include <stdio.h>

int vsprintf (char *str, const char *format, va_list arg);

Arguments

str

A pointer to a string that will receive the formatted output. This string is assumed to be large enough to hold the output.

format

A pointer to a character string that contains the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Return Value

x	The number of bytes written.
Negative value	Indicates an output error occurred.The function sets errno . For a list of possible errno values set, see fprintf in this section.

vsscanf

Reads formatted input based on an argument list.

Format

#include <stdio.h>

int vsscanf (char *str, const char *format, va_list arg);

Arguments

str

The address of the character string that provides the input text to sscanf .

format

A pointer to a character string that contains the format specification.

arg

A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.

Description

This function is the same as the sscanf function except that instead of being called with a variable number of arguments, it is called with an argument list that has been initialized by va_start (and possibly with subsequent va_arg calls).

The vsscanf function is also equivalent to the vfscanf function, except that the first argument specifies a wide-character string rather than a stream. Reaching the end of the wide-character string is the same as encountering EOF for the vfscanf function.

See vsscanf in this section and sscanf in the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

For more information about format and conversion specifications and their corresponding arguments, see the "Understanding Input and Output" chapter of the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.

Return Value

n	The number of successfully matched and assigned input items.
EOF	Indicates that a read error occurred before any conversion. The function sets errno . For a list of the values set by this function, see vfscanf in this section.