United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# utimes

> Sets file access and modification times.

## Format

> #include <time.h>

> int utimes (const char *path, const struct timeval times[2]);

## Argument

> ### path

> A pointer to a file.

> ### times

> an array of `timeval` structures. The first array member represents the date and time of last access, and the second member represents the date and time of last modification. The times in the `timeval` structure are measured in seconds and microseconds since the Epoch, although rounding toward the nearest second may occur.

## Description

> The `utimes` function sets the access and modification times of the file pointed to by the path argument to the value of the times argument. The `utimes` function allows time specifications accurate to the microsecond.

> If the times argument is a null pointer, the access and modification times of the file are set to the current time. The effective user ID of the process must be the same as the owner of the file, or must have write access to the file or appropriate privileges to use this call in this manner.

> Upon completion, `utimes` marks the time of the last file status change, st_ctime, for update.

> Note (ALPHA ONLY) On OpenVMS Alpha systems, the `stat` , `fstat` , `utime` , and `utimes` functions have been enhanced to take advantage of the new file-system support for POSIX-compliant file timestamps. This support is available only on ODS-5 devices on OpenVMS Alpha systems beginning with a version of OpenVMS Alpha after Version 7.3. Before this change, the `stat` and `fstat` functions were setting the values of the st_ctime, st_mtime, and st_atime fields based on the following file attributes: st_ctime - ATR$C_CREDATE (file creation time) st_mtime - ATR$C_REVDATE (file revision time) st_atime - was always set to st_mtime because no support for file access time was available Also, for the file-modification time, `utime` and `utimes` were modifying the ATR$C_REVDATE file attribute, and ignoring the file-access-time argument. After the change, for a file on an ODS-5 device, the `stat` and `fstat` functions set the values of the st_ctime, st_mtime, and st_atime fields based on the following new file attributes: st_ctime - ATR$C_ATTDATE (last attribute modification time) st_mtime - ATR$C_MODDATE (last data modification time) st_atime - ATR$C_ACCDATE (last access time) If ATR$C_ACCDATE is zero, as on an ODS-2 device, the `stat` and `fstat` functions set st_atime to st_mtime. For the file-modification time, the `utime` and `utimes` functions modify both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For the file-access time, these functions modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device has no effect. For compatibility, the old behavior of `stat` , `fstat` , `utime` and `utimes` remains the default, regardless of the kind of device. The new behavior must be explicitly enabled by defining the DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before invoking the application. Setting this logical does not affect the behavior of `stat` , `fstat` , `utime` and `utimes` for files on an ODS-2 device.

## Return Values

> 0 | Successful execution.
> -1 | Indicates an error. The file times do not change and the function sets `errno` to one of the following values: The `utimes` function will fail if: EACCES -- Search permission is denied by a component of the path prefix; or the times argument is a null pointer and the effective user ID of the process does not match the owner of the file and write access is denied. ELOOP -- Too many symbolic links were encountered in resolving path. ENAMETOOLONG -- The length of the path argument exceeds {PATH_MAX}, a path name component is longer than {NAME_MAX}, or a path name resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}. ENOENT -- A component of path does not name an existing file, or path is an empty string. ENOTDIR -- A component of the path prefix is not a directory. EPERM --The times argument is not a null pointer and the calling process' effective user ID has write-access to the file but does not match the owner of the file and the calling process does not have the appropriate privileges. EROFS -- The file system containing the file is read-only.

# unsetenv

> Deletes all instances of the environment variable name from the environment list.

## Format

> #include <stdlib.h>

> void unsetenv (const char *name);

## Arguments

> ### name

> The environment variable to delete from the environment list.

## Description

> This function deletes all instances of the variable name pointed to by the name argument from the environment list.

# usleep

> Suspends execution for an interval.

## Format

> #include <unistd.h>

> int usleep (unsigned int mseconds);

## Arguments

> ### mseconds

> The number of microseconds to suspend execution for.

## Description

> This function suspends the current process from execution for the number of microseconds specified by the mseconds argument. This argument must be less than 1,000,000. However, if its value is 0, then the call has no effect.

> There is one real-time interval timer for each process. The `usleep` function does not interfere with a previous setting of this timer. If the process set this timer before calling `usleep` and if the time specified by mseconds equals or exceeds the interval timer's prior setting, then the process is awakened shortly before the timer was set to expire.

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error occurred; `errno` is set to EINVAL.

# VAXC$CRTL_INIT

> Allows you to call the Compaq C RTL from other languages or to use the Compaq 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.

## Format

> #include <signal.h>

> void VAXC$CRTL_INIT();

## Description

> The following example shows a Pascal program that calls the Compaq 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 a Compaq 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 Compaq 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.

# VAXC$ESTABLISH

> Used for establishing an OpenVMS exception handler for a particular routine. This function establishes a special Compaq 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.

## Format

> #include <signal.h>

> void VAXC$ESTABLISH (unsigned int (*exception_handler)(void *sigarr, void *mecharr));

## Arguments

> ### 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.

## Description

> `VAXC$ESTABLISH` must be used in place of LIB$ESTABLISH when programs use the Compaq C RTL routines `setjmp` or `longjmp` . See `setjmp` and `longjmp` , or `sigsetjmp` and `siglongjmp` in this section.

> You can only invoke the `VAXC$ESTABLISH` function from a Compaq C for OpenVMS function, because it relies on the allocation of data space on the run-time stack by the Compaq C compiler. Calling the OpenVMS system library routine LIB$ESTABLISH directly from a Compaq 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 a Compaq 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)

# va_arg

> Used for returning the next item in the argument list.

## Format

> #include <stdarg.h> (ANSI C)

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

> type va_arg (va_list ap, type);

## Arguments

> ### 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.

## Description

> This 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 Chapter 3, Example 3-6.

# va_count

> Returns the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the argument list.

## Format

> #include <stdarg.h> (ANSI C)

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

> void va_count (int *count);

## Argument

> ### count

> An integer variable name in which the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) is returned.

## Description

> This function 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 systems.

> This function is specific to Compaq C for OpenVMS Systems and is not portable.

# va_end

> Finishes the `<varargs.h>` or `<stdarg.h>` session.

## Format

> #include <stdarg.h> (ANSI C)

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

> void va_end (va_list ap);

## Argument

> ### ap

> The object used to traverse the argument list length. You must declare and use the argument ap as shown in this format section.

## Description

> 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 Chapter 3, Example 3-6.

# va_start_1, va_start

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

## Format

> #include <varargs.h> (DEC 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.

Previous | Next | Contents | Index

privacy and legal statement