United States

Compaq C

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

Previous | Contents | Index

## 10.9.1 Character Classification Functions

The LC_CTYPE category in a locale classifies the characters in the locale's codeset into different types (alphabetic, numeric, lowercase, uppercase, and so on). There are two sets of functions, one for wide characters and one for single-byte characters, that test whether a character is of a specific type. The `is*` functions test single-byte characters, and the `isw*` functions test wide characters.

For example, the `iswalnum` function tests if a wide character is classed as either alphabetic or numeric. It returns a nonzero value if the character is one of these types. For more information about the classification functions see Chapter 3 and the Reference Section.

## 10.9.2 Case Conversion Functions

The LC_CTYPE category defines mapping between pairs of characters of the locale. The most common character mapping is between uppercase and lowercase characters. However, a locale can support other than just case mappings.

Two functions are provided to map one character to another according to the information in the LC_CTYPE category of the locale:

- `wctrans` ---looks for the named mapping (predefined in the locale) between characters.
- `towctrans` ---maps one character to another according to the named mapping given to the `wctrans` function.

Two functions are provided for character case mapping:

- `towlower` ---maps an uppercase wide character to its lowercase equivalent.
- `towupper` ---maps a lowercase wide character to its uppercase equivalent.

For more information about these functions, see the Reference Section.

## 10.9.3 Functions for Input and Output of Wide Characters

The set of input and output functions manages wide characters and wide-character strings.

Read Functions

The functions for reading wide characters and wide-character strings are `fgetwc` , `fgetws` , `getwc` , and `getwchar` .

There is also an `ungetwc` function that pushes a wide character back into the input stream.

Write Functions

The functions for writing wide characters and wide-character strings are `fputwc` , `fputws` , `putwc` , and `putwchar` .

Scan Functions

All the scan functions allow for a culture-specific radix character, as defined in the LC_NUMERIC category of the current locale.

The %lc, %C, %ls, and %S conversion specifiers enable the scan functions `fwscanf` , `wscanf` , `swscanf` , `fscanf` , `scanf` , and `sscanf` to read in wide characters.

Print Functions

All the print functions can format numeric values according to the data in the LC_NUMERIC category of the current locale.

The %lc, %C and %ls, %S conversion specifiers used with print functions convert wide characters to multibyte characters and print the resulting characters.

See Chapter 2 for details of all input and output functions.

## 10.9.4 Functions for Converting Multibyte and Wide Characters

Wide characters are used internally by an application to manage single-byte or multibyte characters. However, text files are generally stored in multibyte character format. To process these files, the multibyte characters need converting to wide-character format. This can be achieved using the following functions:

- `mbtowc` , `mbrtowc` , `btowc` ---convert one multibyte character to a wide character.
- `mbsrtowcs` , `mbstowcs` ---convert a multibyte character string to a wide-character string.

Similarly, the following functions convert wide characters into their multibyte equivalent:

- `wcrtomb` , `wctomb` , `wctob` ---convert a single wide character to a multibyte character.
- `wcsrtombs` , `wcstombs` ---convert a wide-character string to a multibyte character string.

Associated with these conversion functions, the `mblen` and `mbrlen` functions are used to determine the size of a multibyte character.

Several of the wide-character functions take an argument of type "pointer to `mbstate_t` ", where `mbstate_t` is an opaque datatype (like `FILE` or `fpos_t` ) intended to keep the conversion state for the state-dependent codesets.

## 10.9.5 Functions for Manipulating Wide-Character Strings and Arrays

The Compaq C RTL contains a set of functions (the `wcs` * and `wmem` * functions) that manipulate wide-character strings. For example, the `wcscat` function appends a wide-character string to the end of another string in the same way that the `strcat` function works on character strings of type char.

See Chapter 3 for details of the string manipulation functions.

# 10.10 Collating Functions

In an international environment, string comparison functions need to allow for multipass collations. The collation requirements include:

- Ordering accented characters.
- Collating a character sequence as a single character. For example, ch in Spanish should be collated after c but before d.
- Collating a single character as a two-character sequence.
- Ignoring some characters.

Collating information is stored in the LC_COLLATE category of a locale. The Compaq C RTL includes the `strcoll` and `wcscoll` functions that use this collating information to compare two strings.

Multipass collations by `strcoll` or `wcscoll` can be slower than using the `strcmp` or `wcscmp` functions. If your program needs to do many string comparisons using `strcoll` or `wcscoll` , it may be quicker to transform the strings once, using the `strxfrm` or `wcsxfrm` function, and then use the `strcmp` or `wcscmp` function.

The term collation refers to the relative order of characters. The collation order is locale-specific and might ignore some characters. For example, an American dictionary ignores the hyphen in words and lists take-out between takeoff and takeover.

Comparison, on the other hand, refers to the examination of characters for sameness or difference. For example, takeout and take-out are different words, although they may collate the same.

Suppose an application sorts a list of words so it can later perform a binary search on the list to quickly retrieve a word. Using `strcmp` , take-in, take-out, and take-up would be grouped in one part of the table. Using `strcoll` and a locale that ignores hyphens, take-out would be grouped with takeoff and takeover, and would be considered a duplicate of takeout. To avoid a binary search finding takeout as a duplicate of take-out, an application would most likely use `strcmp` rather than `strcoll` for forming a binary tree.

# Chapter 11
Date/Time Functions

This chapter describes the date/time functions available with Compaq C for OpenVMS Systems. For more detailed information on each function, see the Reference Section.

Table 11-1 Date/Time Functions
Function | Description
--- | ---
`asctime` | Converts a broken-down time from `localtime` into a 26-character string.
`ctime` | Converts a time, in seconds, since 00:00:00, January 1, 1970 to an ASCII string of the form generated by the `asctime` function.
`ftime` | Returns the elapsed time since 00:00:00, January 1, 1970 in the structure pointed to by its argument.
`getclock` | Gets the current value of the system-wide clock.
`gettimeofday` | Gets the date and time.
`gmtime` | Converts time units to GMT (Greenwich Mean Time).
`localtime` | Converts a time (expressed as the number of seconds elapsed since 00:00:00, January 1, 1970) into hours, minutes, seconds, and so on.
`mktime` | Converts a local time structure to a calendar time value.
`time` | Returns the time elapsed since 00:00:00, January 1, 1970, in seconds.
`tzset` | Sets and accesses time-zone conversion.

Also, the time-related information returned by `fstat` and `stat` uses the new date/time model described in the next section.

# 11.1 Date/Time Support Models

Beginning with OpenVMS Version 7.0, the Compaq C RTL changed its date/time support model from one based on local time to one based on Universal Coordinated Time (UTC). This allows the Compaq C RTL to implement ANSI C/POSIX functionality that previously could not be implemented. A UTC time-based model also makes the Compaq C RTL compatible with the behavior of the Tru64 UNIX time functions.

By default, newly compiled programs will generate entry points into UTC-based date/time routines.

For compatibility with OpenVMS systems prior to Version 7.0, previously compiled programs that relink on an OpenVMS Version 7.0 system will retain local-time-based date/time support. Relinking alone will not access UTC support.

Compiling programs with the `_DECC_V4_SOURCE` and `_VMS_V6_SOURCE` feature-test macros defined will also enable local-time-based entry points. That is, the new OpenVMS Version 7.0 date/time functions will not be enabled.

Functions with both UTC-based and local-time-based entry points are:

    ctime           mktime
    fstat           stat
    ftime           strftime
    gmtime          time
    localtime       wcsftime

Note Introducing a UTC-based, date/time model implies a certain loss of performance because time-related functions supporting UTC must read and interpret time-zone files instead of doing simple computations in memory as was done for the date/time model based on local time. To decrease this performance degradation, OpenVMS Version 7.1 and higher can maintain the process-wide cache of time-zone files. The size of the cache (that is, the number of files in the memory) is determined by the value of the logical name DECC$TZ_CACHE_SIZE. The default value is 2. Because the time-zone files are relatively small (about 3 blocks each) you might consider defining DECC$TZ_CACHE_SIZE as the maximum number of time zones used by the application. For example, the default cache size fits an application that does not switch time zones during the run and runs on a system where the TZ environment variable is defined with both Standard and Summer time zone.

# 11.2 Overview of Date/Time Functions

In the UTC-based model, times are represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1, 1970 UTC. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch.

The functions `time` and `ftime` return the time as seconds since the Epoch.

The functions `ctime` , `gmtime` , and `localtime` take as their argument a time value that represents the time in seconds from the Epoch.

The function `mktime` converts a broken-down time, expressed as local time, into a time value in terms of seconds since the Epoch.

The values `st_ctime` , `st_atime` , and `st_mtime` returned in the `stat` structure by the `stat` and `fstat` functions are also in terms of UTC.

Time support new to OpenVMS Version 7.0 includes the functions `tzset` , `gettimeofday` , and `getclock` , and the external variables `tzname` , `timezone` and `daylight` .

The UTC-based time model enables the Compaq C RTL to:

- Implement the ANSI C `gmtime` function, which returns a structure in terms of GMT time.
- Specify the ANSI `tm_isdst` field of the `tm` structure, which specifies whether daylight-savings time is in effect.
- Provide time-related POSIX and X/Open extensions (such as the `tzset` function (which lets you get time information from any timezone), and the external variables `tzname` , `timezone` , and `daylight` .
- Correctly compute the local time for times in the past, something that the time functions like `localtime` need to do.
- Enable `localtime` and `gmtime` , through the use of feature-test macros (see Section 1.5), to return two additional fields: `tm_zone` (an abbreviation of the timezone name) and `tm_gmtoff` (the offset from UTC in seconds) in the `tm` structure they return.

# 11.3 Compaq C RTL Date/Time Computations---UTC and Local Time

Universal Coordinated Time (UTC) is an international standard for measuring time of day. Under the UTC time standard, zero hours occurs when the Greenwich Meridian is at midnight. UTC has the advantage of always increasing, unlike local time, which can go backwards/forwards depending on daylight saving time.

Also, UTC has two additional components:

- A measure of inaccuracy (optional)
- A time-differential factor, which is an offset applied to UTC to derive local time.
  The time-differential factor associates each local time zone with UTC; the time differential factor is applied to UTC to derive local time. (Local times can vary up to --12 hours West of the Greenwich Meridian and +13 hours East of it).

For the Compaq C RTL time support to work correctly on OpenVMS Version 7.0 and higher, the following must be in place:

- Your OpenVMS system must be correctly configured to use a valid OpenVMS TDF. Make sure this is set correctly by checking the value of the SYS$TIMEZONE_DIFFERENTIAL logical. This logical should contain the time difference added to UTC to arrive at your local time.
- Your OpenVMS installation must correctly set the local time zone that describes the location that you want to be your default local time zone. In general, this is the local time zone in which your system is running.

For more information, see the section on setting up your system to compensate for different time zones in your OpenVMS System Manager's Manual: Essentials.

The Compaq C RTL uses local time-zone conversion rules to compute local time from UTC, as follows:

1. The Compaq C RTL internally computes time in terms of UTC.
2. The Compaq C RTL then uses time-zone conversion rules to compute a time-differential factor to apply to UTC to derive local time. See the `tzset` function in the reference section of this manual for more information on the time-zone conversion rules.

By default, the time-zone conversion rules used for computing local time from UTC are specified in time-zone files defined by the SYS$LOCALTIME and SYS$POSIXRULES system logicals. These logicals are set during an OpenVMS installation to point to time-zone files that represent the system's best approximation to local wall-clock time:

- SYS$LOCALTIME defines the time-zone file containing the default conversion rules used by the Compaq C RTL to compute local time.
- SYS$POSIXRULES defines the time-zone file that specifies the default rules to be applied to POSIX-style time zones that do not specify when to change to summer time and back.

SYS$POSIXRULES can be the same as SYS$LOCALTIME. See the `tzset` function for more information.

# 11.4 Time-Zone Conversion Rule Files

The time-zone files pointed to by the SYS$LOCALTIME and SYS$POSIXRULES logicals are part of a public-domain, time-zone support package installed on OpenVMS Version 7.0 and higher systems.

This support package includes a series of source files that describe the timezone conversion rules for computing local time from UTC in world-wide timezones. OpenVMS Version 7.0 and higher systems provide a time-zone compiler called ZIC. The ZIC compiler compiles time-zone source files into binary files that the Compaq C RTL reads to acquire time-zone conversion specifications. For more information on the format of these source files see the OpenVMS system documentation for ZIC.

The time-zone files are organized as follows:

- The root time-zone directory is SYS$COMMON:[SYS$TIMEZONE.SYSTEM]. The system logical SYS$TZDIR is set during installation to point to this area.
- Time-zone source files are found in SYS$COMMON:[SYS$TIMEZONE.SYSTEM.SOURCES].
- Binary time-zone files use SYS$COMMON:[SYS$TIMEZONE.SYSTEM] as their root directory. Some binaries reside in this directory while others reside in its subdirectories.
- Binaries residing in subdirectories are time-zone files that represent specific time zones in a larger geographic area. For example, SYS$COMMON:[SYS$TIMEZONE.SYSTEM] contains a subdirectory for the United States and a subdirectory for Canada, because each of these geographic locations contains several time zones. Each time zone in the US is represented by a time-zone file in the Unites States subdirectory. Each time zone in Canada is represented by a time-zone file in the Canada subdirectory.

Several of the time-zone files have names based on acronyms for the areas that they represent. Table 11-2 lists these acronyms.

Table 11-2 Time-zone Filename Acronyms
Time-Zone Acronym | Description
--- | ---
CET | Central European Time
EET | Eastern European Time
Factory | Specifies No Time Zone
GB-Eire | Great Britain/Ireland
GMT | Greenwich Mean Time
NZ | New Zealand
NZ-CHAT | New Zealand, Chatham Islands
MET | Middle European Time
PRC | Peoples Republic of China
ROC | Republic of China
ROK | Republic of Korea
SystemV | Specific to System V operating system
UCT | Universal Coordinated Time
US | United States
UTC | Universal Coordinated Time
Universal | Universal Coordinated Time
W-SU | Middle European Time
WET | Western European Time

A mechanism is available for you to define and implement your own time-zone rules. For more information, see the OpenVMS system documentation on the ZIC compiler and the description of `tzset` in the reference section of this manual.

Also, the SYS$LOCALTIME and SYS$POSIXRULES system logicals can be redefined to user-supplied time zones.

Previous | Next | Contents | Index

privacy and legal statement