DEC C
Run-Time Library Reference Manual for OpenVMS Systems

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 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 Values

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.

Example

#include <stdlib.h> #include <stdio.h> main () { int status, fd; fd = creat ("system.test", 0); write (fd, "this is an example of using system", 34); close (fd); if system(NULL) { status = system ("DIR/NOHEAD/NOTRAIL/SIZE SYSTEM.TEST"); printf ("system status = %d\n", status); } else printf ("system() not supported.\n"); }

tan

Returns a double value that is the tangent of its radian argument.

Format

#include <math.h>
double tan (double x);

ARGUMENT

x
A radian expressed as a real number.

Return Values

n tan( x)

HUGE_VAL If x is a singular point (...--3<pi symbol>/2, --<pi symbol>/2, <pi symbol>/2...)

tanh

Returns a double value that is the hyperbolic tangent of its double argument.

Format

#include <math.h>
double tanh (double x);

ARGUMENT

x
A real number.

Return Values

n The hyperbolic tangent of the argument.

HUGE_VAL Indicates that the argument is too large; errno is set to ERANGE.

telldir

Returns the current location associated with a specified directory stream. Performs operations on directories.

Format

#include <dirent.h>
long int telldir (DIR *dir_pointer);

ARGUMENTS

dir_pointer
A pointer to the dir structure of an open directory.

DESCRIPTION

This function returns the current location associated with the specified directory stream.

Return Values

x The current location.

--1 Indicates an error and is further specified in the global errno .

tempnam

Constructs the name for a temporary file.

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.

DESCRIPTION

This 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.
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 5 characters for the temporary filename.
See also free in this section.

Return Values

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

NULL An error occurred; errno is set to indicate the error.

time

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

times

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 DEC C RTL uses system-boot time as its reference time.

Return Values

x The elapsed real time in clock ticks since system-boot time.

( clock_t )(--1) Indicates an error.

tmpfile

Creates a temporary file that is opened for update.

Format

#include <stdio.h>
FILE *tmpfile (void);

DESCRIPTION

The file exists only for the duration of the process, or until the file is closed and is preserved across calls to vfork .

Return Values

x The address of a file pointer (defined in the <stdio.h> header file).

NULL Indicates an error.

tmpnam

Generates file names that can be safely used for a temporary file.

Format

#include <stdio.h>
char *tmpnam (char *name);

Function Variants This function also has variants named _tmpnam32 and _tmpnam64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 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.

toascii

Converts its argument, an 8-bit ASCII character, to a 7-bit ASCII character.

Format

#include <ctype.h>
int toascii (char character);

ARGUMENT

character
An object of type char .

Return Value

x A 7-bit ASCII character.

tolower

Converts a character to lowercase.

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_TYPE, 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.

_tolower

Converts an uppercase character to lowercase.

Format

#include <ctype.h>
int _tolower (int character);

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).
The _tolower macro should not be used with arguments that contain side-effect operations. For instance, the following example will not return the expected result:
d = _tolower (c++);

Return Value

x The lowercase letter corresponding to the argument.

touchwin

Places the most recently edited version of the specified window on the terminal screen.

Format

#include <curses.h>
int touchwin (WINDOW *win);

ARGUMENT

win
A pointer to the window.

DESCRIPTION

This function is normally used only to refresh overlapping windows.

Return Values

OK Indicates success.

ERR Indicates an error.

toupper

Converts a character to uppercase.

Format

#include <ctype.h>
int toupper (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 a lowercase letter, and there is a corresponding uppercase letter, as defined by character type information in the program locale category LC_TYPE, the corresponding uppercase letter is returned.
If the argument is not a lowercase character, it is returned unchanged.

Return Value

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

_toupper

Converts a lowercase character to uppercase.

Format

#include <ctype.h>
int _toupper (int character);

ARGUMENT

character
This argument must be an uppercase letter.

DESCRIPTION

The _toupper macro is equivalent to the toupper function except that its argument must be a lowercase letter (not uppercase, not EOF).
The _toupper macro should not be used with arguments that contain side-effect operations. For instance, the following example will not return the expected result:
d = _toupper (c++);

Return Value

x The uppercase letter corresponding to the argument.

towctrans

Maps one wide character to another according to a specified mapping descriptor.

Format

#include <wctype.h>
wint_t towctrans (wint_t wc, wctrans_t desc);

ARGUMENTS

wc
The wide character that you want to map.
desc
Description of the mapping obtained through a call to the wctrans function.

DESCRIPTION

This function maps the wide character specified in wc, using the mapping described by desc .
The current setting of the lc_ctype category must be the same as during the call to the wctrans function that returned the value of desc.

Return Values

x The mapped value of the wc wide character, if this character exists in the mapping described by desc. Otherwise, the value of wc is returned.

towlower

Converts the argument, a wide-character code, to lowercase. If the argument is not an uppercase character, it is returned unchanged.

Format

#include <wctype.h>
(ISO C) #include <wchar.h>
(XPG4) int towlower (wint_t wc);

ARGUMENTS

wc
An object of type wint_t representable as a valid wide character in the current locale, or the value of WEOF. For any other value, the behavior is undefined.

DESCRIPTION

If the argument is an uppercase wide character, the corresponding lowercase wide character (as defined in the LC_CTYPE category of the locale) is returned, if it exists. If it does not exist, the function returns the input argument unchanged.

towupper

Converts the argument, a wide character, to uppercase. If the argument is not a lowercase character, it is returned unchanged.

Format

#include <wctype.h>
(ISO C) #include <wchar.h>
(XPG4) int towupper (wint_t wc);

ARGUMENTS

wc
An object of type wint_t representable as a valid wide character in the current locale, or the value of WEOF. For any other value, the behavior is undefined.

DESCRIPTION

If the argument is a lowercase wide character, the corresponing uppercase wide character (as defined in the LC_CTYPE category of the locale) is returned, if it exists. If it does not exist, the function returns the input argument unchanged.

truncate

Changes file length to a specified length in bytes.

Format

#include <unistd.h>
int truncate (const char *path, off_t length);

ARGUMENTS

path
The name of a file that is to be truncated. This argument must point to a pathname that names a regular file for which the calling process has write permission.
length
The new length of the file in bytes.

DESCRIPTION

This function changes the length of a file to the size in bytes specified by the length argument.
If the new length is less than the previous length, the function removes all data beyond length bytes from the specified file. All file data between the new End-of-File and the previous End-of-File is discarded.
For stream files, if the new length is greater than the previous length, new file data between the previous End-of-File and the new End-of-File is added, consisting of all zeros. (For record files, it is not possible to extend the file in this manner.)

Return Values

0 Indicates success.

--1 An error occurred; errno is set to indicate the error.

ttyname

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

Format

#include <unixio.h>
char *ttyname (void);

DESCRIPTION

This function is provided only for UNIX compatibility and has limited use in the OpenVMS environment.

Return Values

x A pointer to a null-terminated string.

0 Indicates that SYS$INPUT is not a TTY device.

tzset

Sets and accesses time-zone conversion.

Format

#include <time.h>
void tzset (void);
extern char *tzname[];
extern long int timezone;
extern int daylight;

DESCRIPTION

This function initializes time conversion information used by the ctime , localtime , mktime , strftime , and wcsftime functions.
The tzset function sets the following external variables:
tzname is set as follows, where "std" is a 3-byte name for the standard time zone, and "dst" is a 3-byte name for the Daylight Savings Time zone:
tzname[0] = "std" tzname[1] = "dst"
daylight is set to 0 if Daylight Savings Time should never be applied to the time zone. Otherwise, daylight is set to 1.
timezone is set to the difference between UTC and local standard time.
The environment variable tz specifies how tzset initializes time conversion information:

If tz is absent from the environment, the implementation-dependent time-zone information is used, as follows:

The best available approximation to local wall-clock time is used, as defined by the system logical SYS$LOCALTIME, which points to a tzfile format file that describes default time-zone rules.
This system logical is set during the installation of OpenVMS Version 7.0 or higher to define a time-zone file based off the root directory SYS$COMMON:[SYS$ZONEINFO.SYSTEM]. ¹

If tz appears in the environment but its value is a null string, Coordinated Universal Time (UTC) is used (without leap-second correction).
If tz appears in the environment and its value is not a null string, the value has one of three formats, as described in Table REF-11.
Table REF-11 Time-Zone Initialization Rules
tz Format Meaning

: UTC is used.

: pathname The characters following the colon specify the pathname of a tzfile format file from which to read the time-conversion information. A pathname beginning with a slash (/) represents an absolute pathname; otherwise, the pathname is relative to the system time-conversion information directory specified by SYS$TZDIR, which by default is SYS$COMMON:[SYS$ZONEINFO.SYSTEM].

stdoffset[ dst[ offset]
[,rule]] The value is first used as the pathname of a file (as described for the : pathname format) from which to read the time-conversion information.
If that file cannot be read, the value is then interpreted as a direct specification of the time-conversion information, as follows:

std and dst---Three or more characters that are the designation for the time zone:

std---Standard time zone. Required.
dst---Daylight Savings Time zone. Optional. If dst is omitted, Daylight Savings Time does not apply.

Uppercase and lowercase letters are explicitly allowed. Any characters are allowed, except the following:

digits
leading colon (:)
comma (,)
minus (-)
plus (+)
ASCII null character
offset---The value added to the local time to arrive at UTC. The offset has the following format:
hh[: mm[: ss]]

In this format:

hh (hours) is a one-or two-digit value of 0--24.
mm (minutes) is a value of 0--59. (optional)
ss (seconds) is a value of 0--59. (optional)
The offset following std is required. If no offset follows dst, summer time is assumed, one hour ahead of standard time. You can use one or more digits; the value is always interpreted as a decimal number.
If the time zone is preceded by a minus sign (-), the time zone is East of Greenwich; otherwise, it is West, which can also be indicated by a preceding plus sign (+).
rule---Indicates when to change to and return from summer time. The rule has the form:
start[/ time], end[/ time]

Where:

start is the date when the change from standard time to summer time occurs.
end is the date for returning from summer time to standard time.
If start and end are omitted, the default is the US Daylight Saving Time start and end dates. The format for start and end must be one of the following:

Jn---The Julian day n (1 < n < 365). Leap days are not counted. That is, in all years, including leap years, February 28 is day 59 and March 1 is day 60. You cannot explicitly refer to February 29.
n---The zero based Julian day (0 < n < 365). Leap days are counted, making it possible to refer to February 29.
Mm.n.d---The nth d day of month m where:
0 < n < 5, 0 < d < 6, 1 < m < 12.
When n is 5, it refers to the last d day of month m. Sunday is day 0.

time---The time when, in current time, the change to or return from summer time occurs. The time argument has the same format as offset, except that you cannot use a leading minus (-) or plus (+) sign. If time is not specified, the default is 02:00:00.
If no rule is present in the tz specification, the rules used are those specified by the tzfile format file defined by the system logical SYS$POSIXRULES in the system time-conversion information directory, with the standard and summer time offsets from UTC replaced by those specified by the offset values in tz .
If tz does not specify a tzfile format file and cannot be interpreted as a direct specification, UTC is used.
Note

¹ The DEC C RTL uses a public-domain, time-zone handling package that puts time-zone conversion rules in easily accessible and modifiable files. These files reside in the directory SYS$COMMON:[SYS$ZONEINFO.SYSTEM.SOURCES]. zic converts these files to a special format described by the <tzfile.h> header file. The converted files are created with a root directory of SYS$COMMON:[SYS$ZONEINFO.SYSTEM], which is pointed to by the SYS$TZDIR system logical. This format is readable by the C library functions that handle time-zone information. For example, in the eastern United Stated, SYS$LOCALTIME is defined to be SYS$COMMON:[SYS$ZONEINFO.SYSTEM.US]EASTERN.

Previous Next Contents Index

`tz` Format	Meaning
:	UTC is used.
: pathname	The characters following the colon specify the pathname of a `tzfile` format file from which to read the time-conversion information. A pathname beginning with a slash (/) represents an absolute pathname; otherwise, the pathname is relative to the system time-conversion information directory specified by SYS$TZDIR, which by default is SYS$COMMON:[SYS$ZONEINFO.SYSTEM].
stdoffset[ dst[ offset] [,rule]]	The value is first used as the pathname of a file (as described for the : pathname format) from which to read the time-conversion information. If that file cannot be read, the value is then interpreted as a direct specification of the time-conversion information, as follows:
	std and dst---Three or more characters that are the designation for the time zone: std---Standard time zone. Required. dst---Daylight Savings Time zone. Optional. If dst is omitted, Daylight Savings Time does not apply. Uppercase and lowercase letters are explicitly allowed. Any characters are allowed, except the following: digits leading colon (:) comma (,) minus (-) plus (+) ASCII null character
	offset---The value added to the local time to arrive at UTC. The offset has the following format: hh[: mm[: ss]] In this format: hh (hours) is a one-or two-digit value of 0--24. mm (minutes) is a value of 0--59. (optional) ss (seconds) is a value of 0--59. (optional)
	The offset following std is required. If no offset follows dst, summer time is assumed, one hour ahead of standard time. You can use one or more digits; the value is always interpreted as a decimal number. If the time zone is preceded by a minus sign (-), the time zone is East of Greenwich; otherwise, it is West, which can also be indicated by a preceding plus sign (+).
	rule---Indicates when to change to and return from summer time. The rule has the form: start[/ time], end[/ time] Where: start is the date when the change from standard time to summer time occurs. end is the date for returning from summer time to standard time.
	If start and end are omitted, the default is the US Daylight Saving Time start and end dates. The format for start and end must be one of the following: Jn---The Julian day n (1 < n < 365). Leap days are not counted. That is, in all years, including leap years, February 28 is day 59 and March 1 is day 60. You cannot explicitly refer to February 29. n---The zero based Julian day (0 < n < 365). Leap days are counted, making it possible to refer to February 29. Mm.n.d---The nth d day of month m where: 0 < n < 5, 0 < d < 6, 1 < m < 12. When n is 5, it refers to the last d day of month m. Sunday is day 0.
	time---The time when, in current time, the change to or return from summer time occurs. The time argument has the same format as offset, except that you cannot use a leading minus (-) or plus (+) sign. If time is not specified, the default is 02:00:00. If no rule is present in the `tz` specification, the rules used are those specified by the `tzfile` format file defined by the system logical SYS$POSIXRULES in the system time-conversion information directory, with the standard and summer time offsets from UTC replaced by those specified by the offset values in `tz` . If `tz` does not specify a `tzfile` format file and cannot be interpreted as a direct specification, UTC is used.

n	tan( x)
HUGE_VAL	If x is a singular point (...--3<pi symbol>/2, --<pi symbol>/2, <pi symbol>/2...)

n	The hyperbolic tangent of the argument.
HUGE_VAL	Indicates that the argument is too large; `errno` is set to ERANGE.

x	The current location.
--1	Indicates an error and is further specified in the global `errno` .

x	A pointer to the generated pathname, suitable for use in a subsequent call to the `free` function.
NULL	An error occurred; `errno` is set to indicate the error.

x	The time elapsed past the epoch.
( `time_t` )(--1)	Indicates an error.

x	The elapsed real time in clock ticks since system-boot time.
( `clock_t` )(--1)	Indicates an error.

x	The address of a file pointer (defined in the `<stdio.h>` header file).
NULL	Indicates an error.

0	Indicates success.
--1	An error occurred; `errno` is set to indicate the error.

x	A pointer to a null-terminated string.
0	Indicates that SYS$INPUT is not a TTY device.

DEC CRun-Time Library Reference Manual for OpenVMS Systems

Return Values

Example

tan

Format

ARGUMENT

x

Return Values

tanh

Format

ARGUMENT

x

Return Values

telldir

Format

ARGUMENTS

dir_pointer

DESCRIPTION

Return Values

tempnam

Format

ARGUMENTS

directory

prefix

DESCRIPTION

Return Values

time

Format

ARGUMENT

time_location

Return Values

times

Format

ARGUMENT

buffer

DESCRIPTION

Return Values

tmpfile

Format

DESCRIPTION

Return Values

tmpnam

Format

ARGUMENT

name

Return Value

toascii

Format

ARGUMENT

character

Return Value

tolower

Format

ARGUMENT

character

DESCRIPTION

Return Value

_tolower

Format

ARGUMENT

character

DESCRIPTION

Return Value

touchwin

Format

ARGUMENT

win

DESCRIPTION

Return Values

toupper

Format

ARGUMENT

character

DESCRIPTION

Return Value

_toupper

Format

ARGUMENT

character

DESCRIPTION

DEC C
Run-Time Library Reference Manual for OpenVMS Systems