United States

Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

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 UTC-based time functions, introduced in OpenVMS Version 7.0, had degraded performance compared with the non-UTC-based time functions.

OpenVMS Version 7.1 added a cache for time-zone files to improve performance. The size of the cache is determined by the logical name DECC$TZ_CACHE_SIZE. To accommodate most countries changing the time twice per year, the default cache size is large enough to hold two time-zone files.

See also ctime , localtime , mktime , strftime , and wcsftime in this section.

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

Sample TZ Specification

#1
EST5EDT4,M4.1.0,M10.5.0

This sample TZ specification describes the rule defined in 1987 for the Eastern time zone in the US:

EST (Eastern Standard Time) is the designation for standard time, which is 5 hours behind UTC.
EDT (Eastern Daylight Time) is the designation for summer time, which is 4 hours behind UTC. EDT starts on the first Sunday in April and ends on the last Sunday in October.

Because time was not specified in either case, the changes occur at the default time, which is 2:00 a.m. The start and end dates did not need to be specified, because they are the defaults.

Note

¹ The Compaq 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.

ualarm

Sets or changes the timeout of interval timers.

Format

#include <unistd.h>
useconds_t ualarm (useconds_t mseconds, useconds_t interval);

Arguments

mseconds
Specifies a number of real time microseconds.
interval
Specifies the interval for repeating the timer.

Description

This function causes the SIGALRM signal to be generated for the calling process after the number of real-time microseconds specified by useconds has elapsed. When the interval argument is nonzero, repeated timeout notification occurs with a period in microseconds specified by interval. If the notification signal SIGALRM is not caught or is ignored, the calling process is terminated.
If you call a combination of ualarm and setitimer functions, and the AST status is disabled, the return value is invalid.
If you call a combination of ualarm and setitimer functions, and the AST status is enabled, the return value is valid.
This is because you cannot invoke an AST handler to clear the previous value of the timer when ASTs are disabled or invoked from a handler that was invoked at AST level.

Note
Interactions between ualarm and either alarm , or sleep are unspecified.

See also setitimer in this section.

Return Values

n The number of microseconds remaining from the previous ualarm or setitimer call.

0 No timeouts are pending or ualarm not previously called.

--1 Indicates an error.

umask

Creates a file protection mask that is used when a new file is created, and returns the previous mask value.

Format

#include <stat.h>
mode_t umask (mode_t mode_complement);

Argument

mode_complement
Shows which bits to turn off when a new file is created. See the description of chmod to determine what the bits represent.

Description

Initially, the file protection mask is set from the current process's default file protection. This is done when the C main program starts up or when DECC$CRTL_INIT (or VAXC$CRTL_INIT ) is called. You can change this for all files created by your program by calling umask or you can use chmod to change the file protection on individual files. The file protection of a file created by open or creat is the bitwise AND of the open and creat mode argument with the complement of the value passed to umask on the previous call.

Note
The way to create files with OpenVMS RMS default protections using the UNIX system-call functions umask , mkdir , creat , and open is to call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.

In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.

Return Value

x The old mask value.

uname

Gets system identification information.

Format

#include <utsname.h>
int uname (struct utsname *name);

Arguments

name
The current system identifier.

Description

This function stores null-terminated strings of information identifying the current system into the structure referenced by the name argument.
The utsname structure is defined in the <utsname.h> header file and contains the following members:

sysname Name of the operating system implementation

nodename Network name of this machine

release Release level of the operating system

version Version level of the operating system

machine Machine hardware platform

Return Values

0 Indicates success.

--1 Indicates an error; errno or vaxc$errno is set as appropriate.

ungetc

Pushes a character back into the input stream and leaves the stream positioned before the character.

Format

#include <stdio.h>
int ungetc (int character, FILE *file_ptr);

Arguments

character
A value of type int .
file_ptr
A file pointer.

Description

When using this function, the character is pushed back onto the file indicated by file_ptr.
One pushback is guaranteed, even if there has been no previous activity on the file. The fseek function erases all memory of pushed-back characters. The pushed-back character is not written to the underlying file. If the character to be pushed back is EOF, the operation fails, the input stream is left unchanged, and EOF is returned.
See also fseek and getc in this section.

Return Values

x The push-back character.

EOF Indicates it cannot push the character back.

ungetwc

Pushes a wide character back into the input stream.

Format

#include <wchar.h>
wint_t ungetwc (wint_t wc, FILE *file_ptr);

Arguments

wc
A value of type wint_t .
file_ptr
A file pointer.

Description

When using this function, the wide character is pushed back onto the file indicated by file_ptr.
One push-back is guaranteed, even if there has been no previous activity on the file. If a file positioning function (such as fseek ) is called before the pushed back character is read, the bytes representing the pushed back character are lost.
If the character to be pushed back is WEOF, the operation fails, the input stream is left unchanged, and WEOF is returned.
See also getwc in this section.

Return Values

x The push-back character.

WEOF Indicates that the function cannot push the character back. errno is set to one of the following:

EBADF -- The file descriptor is not valid.
EALREADY -- Operation is already in progress on the same file.
EILSEQ -- Invalid wide-character code detected.

utime

Sets file access and modification times.

Format

#include <types.h>
int utime (const char *path, const struct utimbuf *times);

Argument

path
A pointer to a file.
times
A null pointer or a pointer to a utimbuf structure.

Description

The utime function sets the access and modification times of the file named by the path argument.
If times is a null pointer, the access and modification times of the file are set to the current time. To use utime in this way, the effective user ID of the process must match the owner of the file, or the process must have write permission to the file or have appropriate privileges.
If times is not a null pointer, it is interpreted as a pointer to a utimbuf structure, and the access and modification times are set to the values in the specified structure. Only a process with an effective user ID equal to the user ID of the file or a process with appropriate privileges can use utime this way.
The utimbuf structure is defined by the <utime.h> header. The times in the utimbuf structure are measured in seconds since the Epoch.
Upon successful completion, utime marks the time of the last file status change, st_ctime, to be updated. See the <stat.h> header file.

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 function sets errno to one of the following values:
The utime 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.

Contents

Index

privacy and legal statement

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

n	The number of microseconds remaining from the previous `ualarm` or `setitimer` call.
0	No timeouts are pending or `ualarm` not previously called.
--1	Indicates an error.

sysname	Name of the operating system implementation
nodename	Network name of this machine
release	Release level of the operating system
version	Version level of the operating system
machine	Machine hardware platform

0	Indicates success.
--1	Indicates an error; `errno` or `vaxc$errno` is set as appropriate.

x	The push-back character.
EOF	Indicates it cannot push the character back.

x	The push-back character.
WEOF	Indicates that the function cannot push the character back. `errno` is set to one of the following: EBADF -- The file descriptor is not valid. EALREADY -- Operation is already in progress on the same file. EILSEQ -- Invalid wide-character code detected.

Compaq CRun-Time Library Reference Manual for OpenVMS Systems

ttyname

Format

Description

Return Values

tzset

Format

Description

Sample TZ Specification

ualarm

Format

Arguments

mseconds

interval

Description

Return Values

umask

Format

Argument

mode_complement

Description

Return Value

uname

Format

Arguments

name

Description

Return Values

ungetc

Format

Arguments

character

file_ptr

Description

Return Values

ungetwc

Format

Arguments

wc

file_ptr

Description

Return Values

utime

Format

Argument

path

times

Description

Return Values

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems