HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for
OpenVMS Systems

On Alpha servers,
sysconf
returns the architecture type (2), as given by the $GETSYI system
service.

Integrity processor information is stored in CPUID register 3. This
register contains a 64-bit integer divided into 1-byte fields
indicating version information related to the processor implementation.
The
sysconf
function returns the low-order longword with the following information:

Passes a given string to the host environment to be executed by a
command processor. This function is nonreentrant.

Format

#include <stdlib.h>

int system (const char *string);

Argument

string

A pointer to the string to be executed. If string is NULL, a
nonzero value is returned. The string is a DCL command, not the name of
an image. To execute an image, use one of the
exec
routines.

Description

The
system
function spawns a subprocess and executes the command specified by
string in that subprocess. The
system
function waits for the subprocess to complete before returning the
subprocess status as the return value of the function.

The subprocess is spawned within the
system
call by a call to
vfork
. Because of this, a call to
system
should not be made after a call to
vfork
and before the corresponding call to an
exec
function.

For OpenVMS Version 7.0 and higher systems, if you include
<stdlib.h>
and compile with the _POSIX_EXIT feature-test macro set, then the
system
function returns the status as if it called
waitpid
to wait for the child. Therefore, use the WIFEXITED and WEXITSTATUS
macros (described in the
wait
* routines) to retrieve the exit status in the range of 0 to 255.

You set the _POSIX_EXIT feature-test macro by using /DEFINE=_POSIX_EXIT
or #define _POSIX_EXIT at the top of your file, before any file
inclusions.

Return Value

nonzero value

If
string is NULL, a value of 1 is returned, indicating that the
system
function is supported. If
string is not NULL, the value is the subprocess OpenVMS return
status.

Return Values

Format

#include <stdio.h>

char *tempnam (const char *directory, const char
*prefix, ...;)

Arguments

directory

A pointer to the pathname of the directory where you want to create a
file.

prefix

A pointer to an initial character sequence of the filename. The
prefix argument can be null, or it can point to a string of up
to five characters used as the first characters of the temporary
filename.

...

An optional argument that can be either 1 or 0. If you specify 1,
tempnam
returns the file specification in OpenVMS format. If you specify 0,
tempnam
returns the file specification in UNIX style format. For more
information about UNIX style directory specifications, see
Section 1.3.3.

Description

The
tempnam
function generates filenames for temporary files. It allows you to
control the choice of a directory.

If the directory argument is null or points to a string that
is not a pathname for an appropriate directory, the pathname defined as
P_tmpdir
in the <
stdio.h
> header file is used. For programs running under a detached
process, the directory argument cannot be null.

You can bypass the selection of a pathname by providing the
TMPDIR
environment variable in the user environment. The value of the
TMPDIR
variable is a pathname for the desired temporary file directory.

Use the prefix argument to specify a prefix of up to five
characters for the temporary filename.

The
tempnam
function returns a pointer to the generated pathname, suitable for use
in a subsequent call to the
free
function.

See also
free
.

Note

In contrast to
tmpnam
,
tempnam
does not have to generate a different filename on each call.
tempnam
generates a new filename only if the file with the specified name
exists. If you need a unique filename on each call, use
tmpnam
instead of
tempnam
.

Return Values

x

A pointer to the generated pathname, suitable for use in a subsequent
call to the
free
function.

Returns the time (expressed as Universal Coordinated Time) elapsed
since 00:00:00, January 1, 1970, in seconds.

Format

#include <time.h>

time_t time (time_t *time_location);

Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE
feature-test macros defined enables a local-time-based entry point to
the
time
function that is equivalent to the behavior before OpenVMS Version 7.0.

Argument

time_location

Either NULL or a pointer to the place where the returned time is also
stored. The
time_t
type is defined in the
<time.h>
header file as follows:

typedef unsigned long int time_t;

Return Values

x

The time elapsed past the Epoch.

(
time_t
)( - 1)

Indicates an error. If the value of SYS$TIMEZONE_DIFFERENTIAL logical
is wrong, the function will fail with
errno
set to EINVAL.

Passes back the accumulated times of the current process and its
terminated child processes.

Format

#include <times.h>

clock_t times (struct tms *buffer); (OPENVMS V7.0 AND HIGHER)

void times (tbuffer_t *buffer); (PRE OPENVMS V7.0)

Argument

buffer

A pointer to the terminal buffer.

Description

For both process and children times, the structure breaks down the time
by user and system time. Since the OpenVMS system does not
differentiate between system and user time, all system times are
returned as 0. Accumulated CPU times are returned in 10-millisecond
units.

Only the accumulated times for child processes running a C main program
or a program that calls
VAXC$CRTL_INIT
or
DECC$CRTL_INIT
are included.

On OpenVMS Version 7.0 and higher systems, the
times
function returns the elapsed real time in clock ticks since an
arbitrary reference time in the past (for example, system startup
time). This reference time does not change from one
times
function call to another. The return value can overflow the possible
range of type
clock_t
values. When
times
fails, it returns a value of - 1. The HP C RTL uses
system-boot time as its reference time.

Return Values

Format

#include <stdio.h>

char *tmpnam (char *name);

Function Variants The
tmpnam
function has variants named
_tmpnam32
and
_tmpnam64
for use with 32-bit and 64-bit pointer sizes, respectively. See
Section 1.9 for more information on using pointer-size-specific
functions.

Argument

name

A character string containing a name to use in place of file-name
arguments in functions or macros. Successive calls to
tmpnam
with a null argument cause the function to overwrite the current name.

Return Value

x

If the
name argument is the NULL pointer value NULL,
tmpnam
returns the address of an internal storage area. If
name is not NULL, then it is considered the address of an area
of length
L_tmpnam
(defined in the
<stdio.h>
header file). In this case,
tmpnam
returns the
name argument as the result.

Format

Argument

character

Return Value

Format

#include <ctype.h>

int tolower (int character);

Argument

character

An object of type
int
representable as an
unsigned char
or the value of EOF. For any other value, the behavior is undefined.

Description

If the argument represents an uppercase letter, and there is a
corresponding lowercase letter, as defined by character type
information in the program locale category LC_CTYPE, the corresponding
lowercase letter is returned.

If the argument is not an uppercase character, it is returned unchanged.

Return Value

x

The lowercase letter corresponding to the argument. Or, the unchanged
argument, if it is not an uppercase character.

Format

Argument

character

This argument must be an uppercase letter.

Description

The
_tolower
macro is equivalent to the
tolower
function except that its argument must be an uppercase letter
(not lowercase, not EOF).

As of OpenVMS Version 8.3 and to comply with the C99 ANSI standard and
X/Open Specification, the
_tolower
macro by default does not evaluate its parameter more than once. It
simply calls the
tolower
function. This avoids side effects (such as i++ or function calls)
where the user can tell how many times an expression is evaluated.

To keep the older, optimized
_tolower
macro behavior, compile with /DEFINE=_FAST_TOUPPER. Then, as in
previous releases,
_tolower
optimizes the call to avoid the overhead of a runtime call. The
parameters are checked to determine how to calculate the result,
thereby creating unwanted side effects. Therefore, when compiling with
/DEFINE=_FAST_TOUPPER, do not use the
_tolower
macro with arguments that contain side-effect operations. For instance,
the following example will not return the expected result: