United States

Compaq C

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

Previous | Contents | Index

# div

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

## Format

> #include <stdlib.h>

> div_t div (int numer, int denom);

## Arguments

> ### numer

> A numerator of type `int` .

> ### denom

> A denominator of type `int` .

## Description

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

>     typedef struct
>             {
>                  int   quot, rem;
>             } div_t;

# dlclose

> Deallocates the address space for a shared library.

## Format

> #include <stdio.h>

> void dlclose (void *handle);

## Arguments

> ### handle

> Pointer to the shared library.

## Description

> The `dlclose` function deallocates the address space allocated by the Compaq C RTL for the handle.

> There is no way on OpenVMS systems to "unload" a shareable image dynamically loaded by the LIB$FIND_IMAGE_SYMBOL routine, which is the routine called by the `dlsym` function. In other words, there is no way on OpenVMS systems to release the address space occupied by the shareable image brought into memory by `dlsym` .

# dlerror

> Returns a string describing the last error that occurred from a call to `dlopen` , `dlclose` , or `dlsym` .

## Format

> #include <stdio.h>

> char *dlerror (void);

## Description

## Return Values

> x | A string describing the last error that occurred from a call to `dlopen` , `dlclose` , or `dlsym` .

# dlopen

> Provides an interface to the dynamic library loader to allow shareable images to be loaded and called at run time.

## Format

> #include <stdio.h>

> void *dlopen (char *pathname, int mode);

## Arguments

> ### pathname

> The name of the shareable image. This name is saved for subsequent use by the `dlsym` function.

> ### mode

> This parameter is ignored on OpenVMS systems.

## Description

> This function provides an interface to the dynamic library loader to allow shareable images to be loaded and called at run time.

> The `dlopen` function does not load a shareable image but rather saves its pathname argument for subsequent use by the `dlsym` function. `dlsym` is the function that actually loads the shareable image through a call to LIB$FIND_IMAGE_SYMBOL.

> The pathname argument of the `dlopen` function must be the name of the shareable image. This name is passed as-is by the `dlsym` function to the LIB$FIND_IMAGE_SYMBOL routine as the filename argument. No image-name argument is specified in the call to LIB$FIND_IMAGE_SYMBOL, so default file specification of SYS$SHARE:.EXE is applied to the image name.

> The `dlopen` function returns a handle that is used by a `dlsym` or `dlclose` call. If an error occurs, a NULL pointer is returned.

## Return Values

> x | A handle to be used by a `dlsym` or `dlclose` call.
> NULL | Indicates an error.

# dlsym

> Returns the address of the symbol name found in a shareable image.

## Format

> #include <stdio.h>

> void *dlsym (void *handle, char *name);

## Arguments

> ### handle

> Pointer to the shareable image.

## Description

> The `dlsym` function returns the address of the symbol name found in the shareable image corresponding to handle. If the symbol is not found, a NULL pointer is returned.

## Return Values

> x | Address of the symbol name found.
> NULL | Indicates that the symbol was not found.

# drand48

> Generates uniformly distributed pseudorandom number sequences. Returns 48-bit, nonnegative, double-precision floating-point values.

## Format

> #include <stdlib.h>

> double drand48 (void);

## Description

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

> It returns non-negative, double-precision, floating-point values uniformly distributed over the range of y values such that 0.0 <= y < 1.0.

> Before you call `drand48` , use either `srand48` , `seed48` , or `lcong48` to initialize the random number generator. You must initalize prior to invoking the `drand48` 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 `drand48` 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 `lcong48` , the multiplier value a and the addend value c are:

>          a = 5DEECE66D16 = 2736731631558
>          c = B16 = 138

> The values returned by `drand48` are computed by first generating the next 48-bit Xi in the sequence. Then the appropriate bits, according to the type of returned data item, are copied from the high-order (most significant) bits of Xi and transformed into the returned value.

> See also `srand48` , `seed48` , `lcong48` , `lrand48` , and `mrand48` in this section.

## Return Values

> n | A nonnegative, double-precision, floating-point value.

# dup, dup2

> Allocate a new descriptor that refers to a file specified by a file descriptor returned by `open` , `creat` , or `pipe` .

## Format

> #include <unistd.h>

> int dup (int file_desc1);

> int dup2 (int file_desc1, int file_desc2);

## Arguments

> ### file_desc1

> The file descriptor being duplicated.

> ### file_desc2

> The new file descriptor to be assigned to the file designated by file_desc1.

## Description

> The `dup` function causes a previously unallocated descriptor to refer to its argument, while the `dup2` function causes its second argument to refer to the same file as its first argument.

> The argument file_desc1 is invalid if it does not describe an open file; file_desc2 is invalid if the new file descriptor cannot be allocated. If file_desc2 is connected to an open file, that file is closed.

## Return Values

> n | The new file descriptor.
> --1 | Indicates that an invalid argument was passed to the function.

# [no]echo

> Set the terminal so that characters may or may not be echoed on the terminal screen. This mode of single-character input is only supported with Curses.

## Format

> #include <curses.h>

> void echo (void);

> void noecho (void);

## Description

> The `noecho` function may be helpful when accepting input from the terminal screen with `wgetch` and `wgetstr` ; it prevents the input characters from being written onto the screen.

# ecvt

> Converts its argument to a null-terminated string of ASCII digits and returns the address of the string. The string is stored in a thread-specific memory location created by the Compaq C RTL.

## Format

> #include <stdlib.h>

> char *ecvt (double value, int ndigits, int *decpt, int *sign);

## Arguments

> ### value

> An object of type `double` that is converted to a null-terminated string of ASCII digits.

> ### ndigits

> The number of ASCII digits to be used in the converted string.

> ### decpt

> The position of the decimal point relative to the first character in the returned string. A negative `int` value means that the decimal point is decpt number of spaces to the left of the returned digits, (the spaces being filled with zeros). A 0 value means that the decimal point is immediately to the left of the first digit in the returned string.

> ### sign

> An integer value that indicates whether the value argument is positive or negative. If value is negative, the function places a nonzero value at the address specified by sign. Otherwise, the function assigns 0 to the address specified by sign.

## Description

> This function converts value to a null-terminated string of length ndigits, and returns a pointer to it. The resulting low-order digit is rounded to the correct digit for outputting ndigits digits in C E-format. The decpt argument is assigned the position of the decimal point relative to the first character in the string.

> Repeated calls to the `ecvt` function overwrite any existing string.

> The `ecvt` , `fcvt` , and `gcvt` functions represent the following special values specified in the IEEE Standard for floating-point arithmetic:

> Value | Representation
> --- | ---
> Quiet NaN | NaNQ
> Signalling NaN | NaNS
> +Infinity | Infinity
> --Infinity | --Infinity

> The sign associated with each of these values is stored into the sign argument. In IEEE floating-point representation, a value of 0 (zero) can be positive or negative, as set by the sign argument.

> See also `gcvt` and `fcvt` in this section.

## Return Value

> x | The value of the converted string.

# endwin

> Clears the terminal screen and frees any virtual memory allocated to Curses data structures.

## Format

> #include <curses.h>

> void endwin (void);

## Description

> A program that calls Curses functions must call the `endwin` function before exiting to restore the previous environment of the terminal screen.

# erand48

> Generate uniformly distributed pseudorandom number sequences. Returns 48-bit nonnegative, double-precision, floating-point values.

## Format

> #include <stdlib.h>

> double erand48 (unsigned short int xsubi[3]);

## Argument

> ### xsubi

> An array of three `short int` , which form a 48-bit integer when concatentated together.

## Description

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

> It returns nonnegative, double-precision, floating-point values uniformly distributed over the range of y values, such that, 0.0 <= y < 1.0.

> The `erand48` 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 `erand48` function requires that the calling program pass an array as the xsubi argument. For the first call, the array must be initialized to the 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, the `erand48` function 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 Values

> n | A nonnegative, double-precision, floating-point value.

# [w]erase

> Erase the window by painting it with blanks. The `erase` function acts on the `stdscr` window.

## Format

> #include <curses.h>

> int erase();

> int werase (WINDOW *win);

## Argument

> ### win

> A pointer to the window.

## Description

> Both the `erase` and `werase` functions leave the cursor at the current position on the terminal screen after completion; they do not return the cursor to the home coordinates of (0,0).

## Return Values

> OK | Indicates success.
> ERR | Indicates an error.

# execl

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execl (const char *file_spec, const char *arg0, ..., (char *)0); (ISO POSIX-1)

> int execl (char *file_spec, ...); (COMPATABILITY)

## Arguments

> ### file_spec

> The full file specification of a new image to be activated in the child process.

> ### arg0, ...

> A sequence of pointers to null-terminated character strings.

> If the POSIX-1 format is used, at least one argument must be present and must point to a string that is the same as the new process file name (or its last component). (This pointer can also be the NULL pointer, but then `execle` would accomplish nothing.) The last pointer must be the NULL pointer. This is also the convention if the compatibility format is used.

## Description

> To understand how the exec functions operate, consider how the OpenVMS system calls any Compaq C program, as shown in the following syntax:

> `int main (int argc, char *argv[], char *envp[]);`

> The identifier argc is the argument count; argv is an array of argument strings. The first member of the array (argv[0]) contains the name of the image. The arguments are placed in subsequent elements of the array. The last element of the array is always the NULL pointer.

> An exec function calls a child process in the same way that the run-time system calls any other Compaq C program. The exec functions pass the name of the image to be activated in the child; this value is placed in argv[0]. However, the functions differ in the way they pass arguments and environment information to the child:

> - Arguments can be passed in separate character strings ( `execl` , `execle` , and `execlp` ) or in an array of character strings ( `execv` , `execve` , and `execvp` ).
> - The environment can be explicitly passed in an array ( `execle` and `execve` ) or taken from the parent's environment ( `execl` , `execv` , `execlp` , and `execvp` ).

> If `vfork` was called before invoking an exec function, then when the exec function completes, control is returned to the parent process at the point of the `vfork` call. If `vfork` was not called, the exec function waits until the child has completed execution and then exits the parent process. See `vfork` in this section and Chapter 5 for more information.

## Return Value

> --1 | Indicates failure.

# execle

> Passes the name of an image to be activated in a child process. This function is nonreentrant.

## Format

> #include <unistd.h>

> int execle (char *file_spec, char *arg0, ..., (char *)0, char *envp[]); (ISO POSIX-1)

> int execle (char *file_spec, ...); (COMPATABILITY)

## Arguments

> ### file_spec

> The full file specification of a new image to be activated in the child process.

> ### arg0, ...

> A sequence of pointers to null-terminated character strings.

> If the POSIX-1 format is used, at least one argument must be present and must point to a string that is the same as the new process file name (or its last component). (This pointer can also be the NULL pointer, but then `execle` would accomplish nothing.) The last pointer must be the NULL pointer. This is also the convention if the compatibility format is used.

> ### envp

> An array of strings that specifies the program's environment. Each string in envp has the following form:

> `name = value`

> The name can be one of the following names and the value is a null-terminated string to be associated with the name:

> - HOME---Your login directory
> - TERM---The type of terminal being used
> - PATH---The default device and directory
> - USER---The name of the user who initiated the process

> The last element in envp must be the NULL pointer.

> When the operating system executes the program, it places a copy of the current environment vector (envp) in the external variable environ.

## Description

> See `execl` in this section for a description of how the exec functions operate.

## Return Value

> --1 | Indicates failure.

Previous | Next | Contents | Index

privacy and legal statement