| Previous | Contents | Index |
Allows you to call the HP C RTL from other languages or to use the HP C RTL when your main function is not in C. It initializes the run-time environment and establishes both an exit and condition handler. VAXC$CRTL_INIT is a synonym for DECC$CRTL_INIT . Either name invokes the same routine.
#include <signal.h>void VAXC$CRTL_INIT();
The following example shows a Pascal program that calls the HP C RTL using the VAXC$CRTL_INIT function:On OpenVMS VAX systems:
$ PASCAL EXAMPLE $ LINK EXAMPLE,SYS$LIBRARY:DECCRTL/LIB $ TY EXAMPLE.PAS PROGRAM TESTC(input, output); PROCEDURE VAXC$CRTL_INIT; extern; BEGIN VAXC$CRTL_INIT; END $On OpenVMS Alpha systems:
$ PASCAL EXAMPLE $ LINK EXAMPLE,SYS$LIBRARY:VAXCRTL/LIB $ TY EXAMPLE.PAS PROGRAM TESTC(input, output); PROCEDURE VAXC$CRTL_INIT; extern; BEGIN VAXC$CRTL_INIT; END $A shareable image need only call this function if it contains an HP C function for signal handling, environment variables, I/O, exit handling, a default file protection mask, or if it is a child process that should inherit context.
Although many of the initialization activities are performed only once, DECC$CRTL_INIT can safely be called multiple times. On OpenVMS VAX systems, DECC$CRTL_INIT establishes the HP C RTL internal OpenVMS exception handler in the frame of the routine that calls DECC$CRTL_INIT each time DECC$CRTL_INIT is called.
At least one frame in the current call stack must have that handler established for OpenVMS exceptions to get mapped to UNIX signals.
Used for establishing an OpenVMS exception handler for a particular routine. This function establishes a special HP C RTL exception handler in the routine that called it. This special handler catches all RTL-related exceptions that occur in later routines, and passes on all other exceptions to your handler.
#include <signal.h>void VAXC$ESTABLISH (unsigned int (*exception_handler)(void *sigarr, void *mecharr));
exception_handler
The name of the function that you want to establish as an OpenVMS exception handler. You pass a pointer to this function as the parameter to VAXC$ESTABLISH .sigarr
A pointer to the signal array.mecharr
A pointer to the mechanism array.
VAXC$ESTABLISH must be used in place of LIB$ESTABLISH when programs use the HP C RTL routines setjmp or longjmp . See setjmp and longjmp , or sigsetjmp and siglongjmp .You can only invoke the VAXC$ESTABLISH function from an HP C for OpenVMS function, because it relies on the allocation of data space on the run-time stack by the HP C compiler. Calling the OpenVMS system library routine LIB$ESTABLISH directly from an HP C function results in undefined behavior from the setjmp and longjmp functions.
To cause an OpenVMS exception to generate a UNIX style signal, user exception handlers must return SS$_RESIGNAL upon receiving any exception that they do not want to handle. Returning SS$_NORMAL prevents the generation of a UNIX style signal. UNIX signals are generated as if by an exception handler in the stack frame of the main C program. Not all OpenVMS exceptions correspond to UNIX signals. See Chapter 4 for more information on the interaction of OpenVMS exceptions and UNIX style signals.
Calling VAXC$ESTABLISH with an argument of NULL cancels an existing handler in that routine.
Notes
- On OpenVMS Alpha systems, VAXC$ESTABLISH is implemented as a compiler built-in function, not as an HP C RTL function. (ALPHA ONLY)
- On OpenVMS VAX systems, programs compiled with /NAMES=AS_IS should link against SYS$LIBRARY:DECCRTL.OLB to resolve the name VAXC$ESTABLISH , whether or not the program is compiled with the /PREFIX_LIBRARY_ENTRIES switch. This is a restriction in the implementation. (VAX ONLY)
Returns the next item in the argument list.
#include <stdarg.h> (ANSI C)#include <varargs.h> (HP C EXTENSION)
type va_arg (va_list ap, type);
ap
A variable list containing the next argument to be obtained.type
A data type that is used to determine the size of the next item in the list. An argument list can contain items of varying sizes, but the calling routine must determine what type of argument is expected since it cannot be determined at run time.
The va_arg function interprets the object at the address specified by the list incrementor according to type. If there is no corresponding argument, the behavior is undefined.When using va_arg to write portable applications, include the <stdarg.h> header file (defined by the ANSI C standard), not the <varargs.h> header file, and use va_arg only in conjunction with other functions and macros defined in <stdarg.h> .
For an example of argument-list processing using the <stdarg.h> functions and definitions, see Example 3-6.
Returns the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the argument list.
#include <stdarg.h> (ANSI C)#include <varargs.h> (HP C EXTENSION)
void va_count (int count);
count
An integer variable name in which the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) is returned.
The va_count macro places the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the argument list into count. The value returned in count is the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the function argument block not counting the count field itself.If the argument list contains items whose storage requirements are a longword (VAX ONLY) or quadword (ALPHA ONLY) of memory or less, the number in the count argument is also the number of arguments. However, if the argument list contains items that are longer than a longword (VAX ONLY) or a quadword (ALPHA ONLY), count must be interpreted to obtain the number of arguments. Because a double is 8 bytes, it occupies two argument-list positions on OpenVMS VAX systems, and one argument-list position on OpenVMS Alpha and I64 systems.
The va_count macro is specific to HP C for OpenVMS Systems and is not portable.
Finishes the <varargs.h> or <stdarg.h> session.
#include <stdarg.h> (ANSI C)#include <varargs.h> (HP C EXTENSION)
void va_end (va_list ap);
ap
The object used to traverse the argument list length. You must declare and use the argument ap as shown in this format section.
You can execute multiple traversals of the argument list, each delimited by va_start ... va_end . The va_end function sets ap equal to NULL.When using this function to write portable applications, include the <stdarg.h> header file (defined by the ANSI C standard), not the <varargs.h> header file, and use va_end only in conjunction with other routines defined in <stdarg.h> .
For an example of argument-list processing using the <stdarg.h> functions and definitions, see Example 3-6.
Used for initializing a variable to the beginning of the argument list.
#include <varargs.h> (HP C EXTENSION)void va_start (va_list ap);
void va_start_1 (va_list ap, int offset);
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.
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 HP 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 the 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 and I64 systems, 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 HP C User's Guide for OpenVMS Systems or the HP OpenVMS Calling Standard.The preceding version of va_start and va_start_1 is specific to the HP 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:
#include <stdarg.h> (ANSI C)void va_start (va_list ap, parmN);
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.
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 Example 3-6.
Creates an independent child process. This function is nonreentrant.
#include <unistd.h>int vfork (void); (_DECC_V4_SOURCE)
pid_t vfork (void); (NOT _DECC_V4_SOURCE)
The vfork function provided by HP 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.
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.
Prints formatted output based on an argument list.
#include <stdio.h>int vfprintf (FILE *file_ptr, const char *format, va_list ap);
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.ap
A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.
See also vprintf and vsprintf .
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 .
Reads formatted input based on an argument list.
#include <stdio.h>int vfscanf (FILE *file_ptr, const char *format, va_list ap);
file_ptr
A pointer to the file that provides input text.format
A pointer to a string containing the format specification.ap
A list of expressions whose resultant types correspond to the conversion specifications given in the format specifications.
The vfscanf 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 Chapter 2.
This function returns the number of successfully matched and assigned input items.
See also vscanf and vsscanf .
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 -- Nontranslatable OpenVMS error. vaxc$errno contains the OpenVMS 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 -- Nontranslatable OpenVMS error. vaxc$errno contains the OpenVMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.
Writes output to the stream under control of the wide-character format string.
#include <wchar.h>int vfwprintf (FILE *stream, const wchar_t *format, va_list ap);
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.ap
A variable list of the items needed for output.
The vfwprintf function is equivalent to the fwprintf function, with the variable argument list replaced by the ap argument. Initialize ap 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 .
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 OpenVMS error. vaxc$errno contains the OpenVMS 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 OpenVMS error. vaxc$errno contains the OpenVMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.
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); }
| Previous | Next | Contents | Index |