[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language

Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

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 ;¹ Seconds east of Greenwich (Negative values indicate seconds west of Greenwich)

char * tm_zone ;¹ Time zone string, for example "GMT"

¹This field is an extention to the ANSI C 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, log2, log10

Return the logarithm of their arguments.

Format

#include <math.h>
double log (double x);
float logf (float x); (ALPHA ONLY)
long double logl (long double x); (ALPHA ONLY)
double log2 (double x); (ALPHA ONLY)
float log2f (float x); (ALPHA ONLY)
long double log2l (long double x); (ALPHA ONLY)
double log10 (double x);
float log10f (float x); (ALPHA ONLY)
long double log10l (long double x); (ALPHA ONLY)

Argument

x
A real number.

Description

The log functions compute the natural (base e) logarithm of x.
The log2 functions compute the base 2 logarithm of x.
The log10 functions compute the common (base 10) logarithm of x.

Return Values

x The logarithm of the argument (in the appropriate base).

--HUGE_VAL x is 0 ( errno is set to ERANGE), or x is negative ( errno is set to EDOM).

NaN x is NaN; errno is set to EDOM.

log1p (ALPHA ONLY)

Computes ln(1+y) accurately.

Format

#include <math.h>
double log1p (double y);
float log1pf (float y);
long double log1pl (long double y);

Argument

y
A real number greater than -1.

Description

The log1p functions compute ln(1+y) accurately, even for tiny y.

Return Values

x The natural logarithm of (1+ y).

--HUGE_VAL y is less than -1 ( errno is set to EDOM), or y = -1 ( errno is set to ERANGE).

NaN y is NaN; errno is set to EDOM.

logb (ALPHA ONLY)

Returns the radix-independent exponent of the argument.

Format

#include <math.h>
double logb (double x);
float logbf (float x);
long double logbl (long double x);

Argument

x
A nonzero, real number.

Description

The logb functions return the exponent of x, which is the integral part of log₂|x|, as a signed floating-point value, for nonzero x.

Return Values

x The exponent of x.

--HUGE_VAL x = 0.0; errno is set to EDOM.

+Infinity x is +Infinity or -Infinity.

NaN y is NaN; errno is set to EDOM.

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

lrand48

Generates uniformly distributed pseudorandom number sequences. Returns 48-bit signed long integers.

Format

#include <stdlib.h>
long int lrand48 (void);

Description

This function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.
It returns nonnegative, long integers uniformly distributed over the range of y values such that 0 <= y < 2³¹ .
Before you call the lrand48 function use either srand48 , seed48 , or lcong48 to initialize the random number generator. You must initialize prior to invoking the lrand48 function, because it stores the last 48-bit Xi generated into an internal buffer. (Although it is not recommended, constant default initializer values are supplied automatically if the drand48 , lrand48 , or mrand48 functions are called without first calling an initialization function.)
The function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:
Xn+1 = (aXn+c)mod m n >= 0
The argument m equals 2⁴⁸ , so 48-bit integer arithmetic is performed. Unless you invoke the lcong48 function, the multiplier value a and the addend value c are:
a = 5DEECE66D₁₆ = 273673163155₈ c = B₁₆ = 13₈
The value returned by the lrand48 function is computed by first generating the next 48-bit Xi in the sequence. Then the appropriate bits, according to the type of data item to be returned, are copied from the high-order (most significant) bits of Xi and transformed into the returned value.
See also drand48 , lcong48 , mrand48 , seed48 , and srand48 in this section.

Return Values

n Signed nonnegative long integers uniformly distributed over the range 0 <= y < 2 ³¹ .

Contents

Index

HP OpenVMS Systems

Compaq CRun-Time Library Reference Manual for OpenVMS Systems

Return Value

Example

localtime, localtime_r

Format

Argument

timer

result

Description

Return Value

log, log2, log10

Format

Argument

x

Description

Return Values

log1p (ALPHA ONLY)

Format

Argument

y

Description

Return Values

logb (ALPHA ONLY)

Format

Argument

x

Description

Return Values

longjmp

Format

Arguments

env

value

Description

Restrictions

longname

Format

Arguments

termbuf

name

Description

lrand48

Format

Description

Return Values

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems