United States

Compaq C

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

Previous | Contents | Index

# localeconv

> Sets the members of a structure of type `struct lconv` with values appropriate for formatting numeric quantities according to the rules of the current locale.

## Format

> #include <locale.h>

> struct lconv *localeconv (void);

## Description

> This function returns a pointer to the `lconv` structure defined in the `<locale.h>` header file. This structure should not be modified by the program. It is overwritten by calls to `localeconv` , or by calls to the `setlocale` function that change the LC_NUMERIC, LC_MONETARY, or LC_ALL categories.

> The members of the structure are:

> Member | Description
> --- | ---
> `char` *decimal_point | The radix character
> `char` *thousands_sep | The character used to separate groups of digits
> `char` *grouping | The string that defines how digits are grouped in non-monetary values.
> `char` *int_curr_symbol | The international currency symbol
> `char` *currency_symbol | The local currency symbol
> `char` *mon_decimal_point | The radix character used to format monetary values
> `char` *mon_thousands_sep | The character used to separate groups of digits in monetary values
> `char` *mon_grouping | The string that defines how digits are grouped in a monetary value
> `char` *positive_sign | The string used to indicate a non-negative monetary value
> `char` *negative_sign | The string used to indicate a negative monetary value
> `char` int_frac_digits | The number of digits displayed after the radix character in a monetary value formatted with the international currency symbol.
> `char` frac_digits | The number of digits displayed after the radix character in a monetary value
> `char` p_cs_precedes | For positive monetary values, this is set to 1 if the local or international currency symbol precedes the number, and it is set to 0 if the symbol succeeds the number.
> `char` p_sep_by_space | For positive monetary values, this is set to 0 if there is no space between the currency symbol and the number. It is set to 1 if there is a space, and it is set to 2 if there is a space between the symbol and the sign string.
> `char` n_cs_precedes | For negative monetary values, this is set to 1 if the local or international currency symbol precedes the number, and it is set to 0 if the symbol succeeds the number.
> `char` n_sep_by_space | For negative monetary values, this is set to 0 if there is no space between the currency symbol and the number. It is set to 1 if there is a space, and it is set to 2 if there is a space between the symbol and the sign string.
> `char` p_sign_posn | An integer used to indicate where the positive_sign string should be placed for a non-negative monetary quantity.
> `char` n_sign_posn | An integer used to indicate where the negative_sign string should be placed for a negative monetary quantity.

> Members of the structure of type `char` * are pointers to strings, any of which (except decimal_point) can point to "", indicating that the associated value is not available in the current locale or is zero length. Members of the structure of type `char` are positive numbers, any of which can be CHAR_MAX, indicating that the associated value is not available in the current locale. CHAR_MAX is defined in the `<limits.h>` header file.

> Be aware that the value of the CHAR_MAX macro in the `<limits.h>` header depends on whether the program is compiled with the /UNSIGNED_CHAR qualifier:

> - Use the CHAR_MAX macro as an indicator of a non-available value in the current locale only if the program is compiled without /UNSIGNED_CHAR (/NOUNSIGNED_CHAR is the default).
> - If the program is compiled with /UNSIGNED_CHAR, use the SCHAR_MAX macro instead of the CHAR_MAX macro.

> In /NOUNSIGNED_CHAR mode, the values of CHAR_MAX and SCHAR_MAX are the same; therefore, comparison with SCHAR_MAX gives correct results regardless of the /[NO]UNSIGNED_CHAR mode used.

> The members grouping and mon_grouping point to a string that defines the size of each group of digits when formatting a number. Each group size is separated by a semicolon (;). For example, if grouping points to the string 5;3 and the thousands_sep character is a comma (,), the number 123450000 would be formatted as 1,234,50000.

> The elements of grouping and mon_grouping are interpreted as follows:

> Value | Interpretation
> --- | ---
> CHAR_MAX | No further grouping is performed.
> 0 | The previous element is to be used repeatedly for the remainder of the digits.
> other | The integer value is the number of digits that comprise the current group. The next element is examined to determine the size of the next group of digits before the current group.

> The values of p_sign_posn and n_sign_posn are interpreted as follows:

> Value | Interpretation
> --- | ---
> 0 | Parentheses surround the number and currency symbol.
> 1 | The sign string precedes the number and currency symbol.
> 2 | The sign string succeeds the number and currency symbol.
> 3 | The sign string immediately precedes the number and currency symbol.
> 4 | The sign string immediately succeeds the number and currency symbol.

## Return Value

> x | Pointer to the `lconv` structure.

## Example

>     #include <stdlib.h>
>     #include <stdio.h>
>     #include <limits.h>
>     #include <locale.h>
>     #include <string.h>

>     /* The following test program will set up the British English   */
>     /* locale, and then extract the International Currency symbol   */
>     /* and the International Fractional Digits fields for this      */
>     /* locale and print them.                                       */

>     int main()
>     {
>         /* Declare variables                                        */

>         char *return_val;
>         struct lconv *lconv_ptr;

>         /* Load a locale                                            */

>         return_val = (char *) setlocale(LC_ALL, "en_GB.iso8859-1");

>         /* Did the locale load successfully?                        */

>         if (return_val == NULL) {

>             /* It failed to load the locale                         */
>            printf("ERROR : The locale is unknown");
>             exit(EXIT_FAILURE);
>         }

>         /*  Get the lconv structure from the locale                 */

>         lconv_ptr = (struct lconv *) localeconv();

>         /* Compare the international currency symbol string with an */
>         /* empty string. If they are equal, then the international  */
>         /* currency symbol is not defined in the locale.            */

>         if (strcmp(lconv_ptr->int_curr_symbol, "")) {
>             printf("International Currency Symbol = %s\n",
>                    lconv_ptr->int_curr_symbol);
>         }
>         else {
>             printf("International Currency Symbol =");
>             printf("[Not available in this locale]\n");
>         }

>         /* Compare International Fractional Digits with CHAR_MAX.   */
>         /* If they are equal, then International Fractional Digits  */
>         /* are not defined in this locale.                          */

>         if ((unsigned char) (lconv_ptr->int_frac_digits) != CHAR_MAX) {
>             printf("International Fractional Digits = %d\n",
>                    lconv_ptr->int_frac_digits);
>         }
>         else {
>             printf("International Fractional Digits =");
>             printf("[Not available in this locale]\n");
>         }
>     }

> Running the example program produces the following result:

>     International Currency Symbol = GBP
>     International Fractional Digits = 2

# localtime, localtime_r

> Converts a time value to broken-down local time.

## Format

> #include <time.h>

> struct tm *localtime (const time_t *timer);

> struct tm *localtime_r (const time_t *timer, struct tm *result); (ISO POSIX-1)

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

> ### timer

> A pointer to a time in seconds since the Epoch. You can generate this time by using the `time` function or you can supply a time.

> ### result

> A pointer to a `tm` structure where the result is stored. The `tm` structure is defined in the `<time.h>` header file, and is also shown in Table REF-4.

## Description

> The `localtime` and `localtime_r` functions convert the time (in seconds since the Epoch) pointed to by timer into a broken-down time, expressed as a local time, and store it in a `tm` structure.

> The difference between the `localtime_r` and `localtime` functions is that the former stores the result into a user-specified `tm` structure. The latter stores the result into thread-specific static memory allocated by the Compaq C RTL, and which is overwritten by subsequent calls to `localtime` ; you must make a copy if you want to save it.

> On success, `localtime` returns a pointer to the `tm` structure; `localtime_r` returns its second argument. On failure, these functions return the NULL pointer.

> The `tm` structure is defined in the `<time.h>` header file and described in Table REF-4.

> Table REF-4 tm Structure
> int `tm_sec` ; | Seconds after the minute (0-60)
> int `tm_min` ; | Minutes after the hour (0-59)
> int `tm_hour` ; | Hours since midnight (0-23)
> int `tm_mday` ; | Day of the month (1-31)
> int `tm_mon` ; | Months since January (1-11)
> int `tm_year` ; | Years since 1900
> int `tm_wday` ; | Days since Sunday (0-6)
> int `tm_yday` ; | Days since January 1 (0-365)
> int `tm_isdst` ; | Daylight Savings Time flag `tm_isdst` = 0 for Standard Time `tm_isdst` = 1 for Daylight Time
> long `tm_gmtoff` ;1 | Seconds east of Greenwich (Negative values indicate seconds west of Greenwich)
> char * `tm_zone` ;1 | Time zone string, for example "GMT"

1This field is an extention to the ANSI C `tm` structure. It is present unless you compile your program with /STANDARD=ANSI89 or with _DECC_V4_SOURCE defined.

The type `time_t` is defined in the `<time.h>` header file as follows:

    typedef long int time_t

Note Generally speaking, UTC-based time functions can affect in-memory time-zone information, which is process-wide data. However, if the system time zone remains the same during the execution of the application (which is the common case) and the cache of timezone files is enabled (which is the default), then the `_r` variant of the time functions `asctime_r` , `ctime_r` , `gmtime_r` and `localtime_r` , is both thread-safe and AST-reentrant. If, however, the system time zone can change during the execution of the application or the cache of timezone files is not enabled, then both variants of the UTC-based time functions belong to the third class of functions, which are neither thread-safe nor AST-reentrant.

## Return Value

> x | Pointer to a `tm` structure.
> NULL | Indicates failure.

# log, log10

> Return the logarithm of their arguments.

## Format

> #include <math.h>

> double log (double x);

> double log10 (double x);

## Argument

> ### x

> A real number of type `double` .

## Description

> The `log` function performs a natural (base e) logarithm.

> The `log10` functions performs a base 10 logarithm.

## Return Values

> x | The logarithm of the argument (in the appropriate base).
> --HUGE_VAL | Indicates that the argument is 0 or negative; `errno` is set to ERANGE.

# longjmp

> Provides a way to transfer control from a nested series of function invocations back to a predefined point without returning normally; that is, by not using a series of `return` statements. The `longjmp` function restores the context of the environment buffer.

## Format

> #include <setjmp.h>

> void longjmp (jmp_buf env, int value);

## Arguments

> ### env

> The environment buffer, which must be an array of integers long enough to hold the register context of the calling function. The type `jmp_buf` is defined in the `<setjmp.h>` header file. The contents of the general-purpose registers, including the program counter (PC), are stored in the buffer.

> ### value

> Passed from `longjmp` to `setjmp` , and then becomes the subsequent return value of the `setjmp` call. If value is passed as 0, it is converted to 1.

## Description

> When `setjmp` is first called, it returns the value 0. If `longjmp` is then called, naming the same environment as the call to `setjmp` , control is returned to the `setjmp` call as if it had returned normally a second time. The return value of `setjmp` in this second return is the value you supply in the `longjmp` call. To preserve the true value of `setjmp` , the function calling `setjmp` must not be called again until the associated `longjmp` is called.

> The `setjmp` function preserves the hardware general purpose registers, and the `longjmp` function restores them. After a `longjmp` , all variables have their values as of the time of the `longjmp` except for local automatic variables not marked `volatile` . These variables have indeterminate values.

> The `setjmp` and `longjmp` functions rely on the OpenVMS condition-handling facility to effect a nonlocal goto with a signal handler. The `longjmp` function is implemented by generating a Compaq C RTL specified signal and allowing the OpenVMS condition-handling facility to unwind back to the desired destination. The Compaq C RTL must be in control of signal handling for any Compaq C image.

> For Compaq C to be in control of signal handling, you must establish all exception handlers through a call to the `VAXC$ESTABLISH` function (rather than LIB$ESTABLISH). See Section 4.2.5 and the `VAXC$ESTABLISH` function in this section for more information.

> Note There are Alpha specific, non-standard `decc$setjmp` and `decc$fast_longjmp` functions. To use these non-standard functions instead of the standard ones, a program must be compiled with __FAST_SETJMP or __UNIX_SETJMP macros defined. Unlike the standard `longjmp` function, the `decc$fast_longjmp` function does not convert its second argument from 0 to 1. After a call to `decc$fast_longjmp` , a corresponding `setjmp` function returns with the exact value of the second argument specified in the `decc$fast_longjmp` call.

## Restrictions

> You cannot invoke the `longjmp` function from a OpenVMS condition handler. However, you may invoke `longjmp` from a signal handler that has been established for any signal supported by the Compaq C RTL, subject to the following nesting restrictions:
> - The `longjmp` function will not work if invoked from nested signal handlers. The result of the `longjmp` function, when invoked from a signal handler that has been entered as a result of an exception generated in another signal handler, is undefined.
> - Do not invoke the `setjmp` function from a signal handler unless the associated `longjmp` is to be issued before the handling of that signal is completed.
> - Do not invoke the `longjmp` function from within an exit handler (established with `atexit` or SYS$DCLEXH). Exit handlers are invoked after image tear-down, so the destination address of the `longjmp` no longer exists.
> - Invoking `longjmp` from within a signal handler to return to the main thread of execution might leave your program in an inconsistent state. Possible side effects include the inability to perform I/O or to receive any more UNIX signals.

# longname

> Returns the full name of the terminal.

## Format

> #include <curses.h>

> void longname (char *termbuf, char *name);

Function Variants This function also has variants named `_longname32` and `_longname64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### termbuf

> A string containing the name of the terminal.

> ### name

> A character-string buffer with a minimum length of 64 characters.

## Description

> The terminal name is in a readable format so that you can double-check to be sure that Curses has correctly identified your terminal. The dummy argument termbuf is required for UNIX software compatibility and serves no function in the OpenVMS environment. If portability is a concern, you must write a set of dummy routines to perform the functionality provided by the database `termcap` in the UNIX system environment.

Previous | Next | Contents | Index

privacy and legal statement