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 more 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 HP 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 HP 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.

This chapter describes the date/time functions available with HP 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 systemwide 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 Section 11.1.

11.1 Date/Time Support Models

Beginning with OpenVMS Version 7.0, the HP 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 HP C RTL to implement ANSI C/POSIX functionality that previously could not be implemented. A UTC time-based model also makes the HP 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

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 HP 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 time zone), 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 time-zone name) and tm_gmtoff (the offset from UTC in seconds) in the tm structure they return.

Universal Coordinated Time (UTC) is an international standard for measuring time of day. Under the UTC time standard, zero hour 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 HP 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 HP C RTL uses local time-zone conversion rules to compute local time from UTC, as follows:

1. The HP C RTL internally computes time in terms of UTC.
2. The HP 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 HP 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 time-zone conversion rules for computing local time from UTC in worldwide time zones. 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 HP 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.