HP OpenVMS Systems Documentation

Content starts here HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


jrand48

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

Format

#include <stdlib.h>

long int jrand48 (unsigned short int xsubi[3]);


Argument

xsubi

An array of three short int s that form a 48-bit integer when concatentated together.

Description

The jrand48 function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.

The function returns signed long integers uniformly distributed over the range of y values, such that -231 <= y < 231 .

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 248 , so 48-bit integer arithmetic is performed. Unless you invoke the lcong48 function, the multiplier value a and the addend value c are:


      a = 5DEECE66D16 = 2736731631558
      c = B16 = 138

The jrand48 function requires that the calling program pass an array as the xsubi argument, which for the first call must be initialized to the initial value of the pseudorandom-number sequence. Unlike the drand48 function, it is not necessary to call an initialization function prior to the first call.

By using different arguments, jrand48 allows separate modules of a large program to generate several independent sequences of pseudorandom numbers. For example, the sequence of numbers that one module generates does not depend upon how many times the function is called by other modules.


Return Value

n Signed, long integers uniformly distributed over the range -2 31 <= y < 2 31 .

kill

Sends a signal to the process specified by a process ID.

Format

#include <signal.h>

int kill (int pid, int sig);


Arguments

pid

The process ID.

sig

The signal code.

Description

The kill function is restricted to C and C++ programs that include the main function.

The kill function sends a signal to a process, as if the process had called raise . If the signal is not trapped or ignored by the target program, the program exits.

OpenVMS VAX and Alpha implement different rules about what process you are allowed to send signals to. A program always has privileges to send a signal to a child started with vfork / exec . For other processes, the results are determined by the OpenVMS security model for your system.

Because of an OpenVMS restriction, the kill function cannot deliver a signal to a target process that runs an image installed with privileges.

Unless you have system privileges, the sending and receiving processes must have the same user identification code (UIC).

On OpenVMS systems before Version 7.0, kill treats a signal value of 0 as if SIGKILL were specified.

For OpenVMS Version 7.0 and higher systems, if you include <stdlib.h> and compile with the _POSIX_EXIT feature-test macro set, then:

  • If the signal value is 0, kill validates the process ID but does not send any signals.
  • If the process ID is not valid, kill returns - 1 and sets errno to ESRCH.

Return Values

0 Indicates that kill was successfully queued.
- 1 Indicates errors. The receiving process may have a different UIC and you are not a system user, or the receiving process does not exist.

l64a (ALPHA ONLY)

Converts a long integer to a character string.

Format

#include <stdlib.h>

char *l64a (long l);


Argument

l

A long integer that is to be converted to a character string.

Description

The a64l and l64a functions are used to maintain numbers stored in base-64 ASCII characters:
  • a64l converts a character string to a long integer.
  • l64a converts a long integer to a character string.

Each character used to store a long integer represents a numeric value from 0 through 63. Up to six characters can be used to represent a long integer.

The characters are translated as follows:

  • A period (.) represents 0.
  • A slash (/) represents 1.
  • The numbers 0 through 9 represent 2 through 11.
  • Uppercase letters A through Z represent 12 through 37.
  • Lowercase letters a through z represent 38 through 63.

The l64a function takes a long integer and returns a pointer to a corresponding base-64 notation of the least significant 32 bits.

The value returned by l64a is a pointer to a thread-specific buffer whose contents are overwritten on subsequent calls from the same

See also a64l .


Return Value

x Upon successful completion, a pointer to the corresponding base-64 ASCII character-string notation. If the l parameter is 0, l64a returns a pointer to an empty string.

labs

Returns the absolute value of an integer as a long int .

Format

#include <stdlib.h>

long int labs (long int j);


Argument

j

A value of type long int .

lcong48

Initializes a 48-bit uniformly distributed pseudorandom-number sequence.

Format

#include <stdlib.h>

void lcong48 (unsigned short int param[7]);


Argument

param

An array that in turn specifies the initial Xi, the multiplier value a, and the addend value c.

Description

The lcong48 function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.

You can use lcong48 to initialize the random number generator before you call any of the following functions:

drand48
lrand48
mrand48

The lcong48 function specifies the initial Xi value, the multiplier value a, and the addend value c. The param array elements specify the following:

param[0-2] X i
param[3-5] Multiplier a value
param[6] 16-bit addend c value

After lcong48 has been called, a subsequent call to either srand48 or seed48 restores the standard a and c as specified previously.

The lcong48 function does not return a value.

See also drand48 , lrand48 , mrand48 , srand48 , and seed48 .


ldexp

Returns its first argument multiplied by 2 raised to the power of its second argument; that is, x(2n) .

Format

#include <math.h>

double ldexp (double x, int n);

float ldexp (float x, int n); (ALPHA ONLY)

long double ldexp (long double x, int n); (ALPHA ONLY)


Arguments

x

A base value of type double , float , or long double that is to be multiplied by 2n .

n

The integer exponent value to which 2 is raised.

Return Values

x(2 n) The first argument multiplied by 2 raised to the power of the second argument.
0 Underflow occurred; errno is set to ERANGE.
HUGE_VAL Overflow occurred; errno is set to ERANGE.
NaN x is NaN; errno is set to EDOM.

ldiv

Returns the quotient and the remainder after the division of its arguments.

Format

#include <stdlib.h>

ldiv_t ldiv (long int numer, long int denom);


Arguments

numer

A numerator of type long int .

denom

A denominator of type long int .

Description

The type ldiv_t is defined in the <stdlib.h> header file as follows:


typedef struct
        {
             long   quot, rem;
        } ldiv_t;

See also div .


leaveok

Signals Curses to leave the cursor at the current coordinates after an update to the window.

Format

#include <curses.h>

leaveok (WINDOW *win, bool boolf);


Arguments

win

A pointer to the window.

boolf

A Boolean TRUE or FALSE value. If boolf is TRUE, the cursor remains in place after the last update and the coordinate setting on win changes accordingly. If boolf is FALSE, the cursor moves to the currently specified (y,x) coordinates of win.

Description

The leaveok function defaults to moving the cursor to the current coordinates of win. The bool type is defined in the <curses.h> header file as follows:


#define bool int

lgamma (ALPHA ONLY)

Computes the logarithm of the gamma function.

Format

#include <math.h>

double lgamma (double x);

float lgammaf (float x);

long double lgammal (long double x);


Argument

x

A real number. x cannot be 0, a negative integer, or Infinity.

Description

The lgamma functions return the logarithm of the absolute value of gamma of x, or ln(|G(x)|), where G is the gamma function.

The sign of gamma of x is returned in the external integer variable signgam . The x argument cannot be 0, a negative integer, or Infinity.


Return Values

x The logarithmic gamma of the x argument.
-HUGE_VAL The x argument is a negative integer; errno is set to ERANGE.
NaN The x argument is NaN; errno is set to EDOM.
0 Underflow occurred; errno is set to ERANGE.
HUGE_VAL Overflow occurred; errno is set to ERANGE.

link

Creates a new link (directory entry) for an existing file. This function is supported only on volumes that have hard link counts enabled.

Format

#include <unistd.h>

link (const char *path1, const char *path2);


Arguments

path1

Pointer to a pathname naming an existing file.

path2

Pointer to a pathname naming the new directory entry to be created.

Description

The link function atomically creates a new link for the existing file, and the link count of the file is incremented by one.

The link function can be used on directory files.

If link fails, no link is created and the link count of the file remains unchanged.


Return Values

0 Successful completion.
- 1 Indicates an error. The function sets errno to one of the following values:
  • EEXIST -- The link named by path2 exists.
  • EFTYPE -- Wildcards appear in either path1 or path2.
  • EINVAL -- One or both arguments specify a syntactically invalid pathname.
  • ENAMETOOLONG -- The length of path1 or path2 exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX}.
  • EXDEV -- The link named by path2 and the file named by path1 are on different devices.

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

The localeconv 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 nonmonetary 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 nonnegative 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 nonnegative 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 nonavailable 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


Previous Next Contents Index