United States

Compaq C

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

Previous | Contents | Index

# 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 < 231 .

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

# lseek

> Positions a file to an arbitrary byte position and returns the new position as an `int` .

## Format

> #include <unistd.h>

> off_t lseek (int file_desc, off_t offset, int direction);

## Arguments

> ### file_desc

> An integer returned by `open` , `creat` , `dup` , or `dup2` .

> ### offset

> The offset, specified in bytes.

> ### direction

> An integer indicating whether the offset is to be measured forward from the beginning of the file (direction=SEEK_SET), forward from the current position (direction=SEEK_CUR), or backward from the end of the file (direction=SEEK_END).

## Description

> This function can position fixed-length record-access file with no carriage control or a stream-access file on any byte offset, but can position all other files only on record boundaries.

> The available Standard I/O functions position a record file at its first byte, at the end-of-file, or on a record boundary. Therefore, the arguments given to `lseek` must specify either the beginning or end of the file, a 0 offset from the current position (an arbitrary record boundary), or the position returned by a previous, valid `lseek` call.

> For a portable way to position an arbitrary byte location with any type of file, see the `fgetpos` and `fsetpos` functions in this section.

> CAUTION If, while accessing a stream file, you seek beyond the end-of-file and then write to the file, the `lseek` function creates a hole by filling the skipped bytes with zeros. In general, for record files, `lseek` should only be directed to an absolute position that was returned by a previous valid call to `lseek` or to the beginning or end of a file. If a call to `lseek` does not satisfy these conditions, the results are unpredictable.

> See also `open` , `creat` , `dup` , `dup2` , and `fseek` in this section.

## Return Values

> x | The new file position.
> --1 | Indicates that the file descriptor is undefined, or a seek was attempted before the beginning of the file.

# lwait

> Waits for I/O on a specific file to complete.

## Format

> #include <stdio.h>

> int lwait (int fd);

## Argument

> ### fd

> A file descriptor corresponding to an open file.

## Description

> This function is used primarily to wait for completion of pending asynchronous I/O.

## Return Values

> 0 | Indicates successful completion.
> --1 | Indicates an error.

# malloc

> Allocates an area of memory. These functions are AST-reentrant.

## Format

> #include <stdlib.h>

> void *malloc (size_t size);

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

## Argument

> ### size

> The total number of bytes to be allocated.

## Description

> This function allocates a contiguous area of memory whose size, in bytes, is supplied as an argument. The space is not initialized.

> Note The `malloc` routines call the system routine LIB$VM_MALLOC. Because LIB$VM_MALLOC is designed as a general purpose routine to allocate memory, it is called upon in a wide array of scenarios to allocate and reallocate blocks efficiently. The most common usage is the management of smaller blocks of memory, and the most important aspect of memory allocation under these circumstances is efficiency. LIB$VM_MALLOC makes use of its own free space to satisfy requests, once the heap storage is consumed by splitting large blocks and merging adjacent blocks. Memory can still become fragmented, leaving unused blocks. Once heap storage is consumed, LIB$VM_MALLOC manages its own free space and merged blocks to satisfy requests, but varying sizes of memory allocations can cause blocks to be left unused. Because LIB$VM_MALLOC cannot be made to satisfy all situations in the best possible manner, you should perform your own memory management if you have special memory usage needs. This assures the best use of memory for your particular application. The OpenVMS Programming Concepts Manual explains the several memory allocation routines that are available. They are grouped into 3 levels of hierarchy: At the highest level are the RTL Heap Management Routines LIB$GET_VM and LIB$FREE_VM, which provide a mechanism for allocating and freeing blocks of memory of arbitrary size. Also at this level are the routines based on the concept of zones, such as LIB$CREATE_VM_ZONE, and so on. At the next level are the RTL Page Management routines LIB$GET_VM_PAGE and LIB$FREE_VM_PAGE, which allocate a specified number of contiguous pages. At the lowest level are the Memory Management System Services such as $CRETVA and $EXPREG that provide extensive control over address space allocation. Note that at this level, you must manage the allocation precisely.

## Return Values

> x | The address of the first byte, which is aligned on a quadword boundary.
> NULL | Indicates that the function is unable to allocate enough memory. `errno` is set to ENOMEM.

# mblen

> Determines the number of bytes comprising a multibyte character.

## Format

> #include <stdlib.h>

> int mblen (const char *s, size_t n);

## Arguments

> ### s

> A pointer to the multibyte character.

> ### n

> The maximum number of bytes that comprise the multibyte character.

## Description

> If the character is n bytes or less, this function returns the number of bytes comprising the multibyte character pointed to by s. If the character is greater than n bytes, the function returns --1 to indicate an error.

> This function is affected by the LC_CTYPE category of the program's current locale.

## Return Values

> x | The number of bytes that comprise the multibyte character, if the next n or fewer bytes form a valid character.
> 0 | If s is NULL or a pointer to the NULL character.
> --1 | Indicates an error occurred. The function sets `errno` to EILSEQ -- Invalid character detected.

# mbrlen

> Determines the number of bytes comprising a multibyte character.

## Format

> #include <wchar.h>

> size_t mbrlen (const char *s, size_t n, mbstate_t *ps);

## Arguments

> ### s

> A pointer to a multibyte character.

> ### n

> The maximum number of bytes that comprise the multibyte character.

> ### ps

> A pointer to the `mbstate_t` object. If a NULL pointer is specified, the function uses its internal `mbstate_t` object. `mbstate_t` is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

## Description

> The `mbrlen` function is equivalent to the call:

>         mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)

> Where internal is the `mbstate_t` object for the `mbrlen` function.

> If the multibyte character pointed to by s is of n bytes or less, the function returns the number of bytes comprising the character (including any shift sequences).

> If either an encoding error occurs or the next n bytes contribute to an incomplete but potentially valid multibyte character, the function returns --1 or --2, respectively.

> See also `mbrtowc` in this section.

## Return Values

> x | The number of bytes comprising the multibyte character.
> 0 | Indicates that s is a NULL pointer or a pointer to a null byte.
> --1 | Indicates an encoding error, in which case the next n or fewer bytes do not contribute to a complete and valid multibyte character. `errno` is set to EILSEQ; the conversion state is undefined.
> --2 | Indicates an incomplete but potentially valid multibyte character (all n bytes have been processed).

# mbrtowc

> Converts a multibyte character to its wide-character representation.

## Format

> #include <wchar.h>

> size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

## Arguments

> ### pwc

> A pointer to the resulting wide-character code.

> ### s

> A pointer to a multibyte character.

> ### n

> The maximum number of bytes that comprise the multibyte character.

> ### ps

> A pointer to the `mbstate_t` object. If a NULL pointer is specified, the function uses its internal `mbstate_t` object. `mbstate_t` is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

## Description

> If s is a NULL pointer, `mbrtowc` is equivalent to the call:

>         mbrtowc(NULL, "", 1, ps)

> In this case, the values of pwc and n are ignored.

> If s is not a NULL pointer, `mbrtowc` inspects at most n bytes beginning with the byte pointed to by s to determine the number of bytes needed to complete the next multibyte character (including any shift sequences).

> If the function determines that the next multibyte character is completed, it determines the value of the corresponding wide character and then, if pwc is not a NULL pointer, stores that value in the object pointed to by pwc. If the corresponding wide character is the null wide character, the resulting state described is the initial conversion state.

> If `mbrtowc` is called as a counting function, which means that pwc is a NULL pointer and s is neither a NULL pointer nor a pointer to a null byte, the value of the internal `mbstate_t` object will remain unchanged.

## Return Values

> x | The number of bytes comprising the multibyte character.
> 0 | The next n or fewer bytes complete the multibyte character that corresponds to the null wide character (which is the value stored if pwc is not a NULL pointer). The wide-character code corresponding to a null byte is zero.
> --1 | Indicates an encoding error. The next n or fewer bytes do not contribute to a complete and valid multibyte character. `errno` is set to `EILSEQ` . The conversion state is undefined.
> --2 | Indicates an incomplete but potentially valid multibyte character (all n bytes have been processed).

# mbstowcs

> Converts a sequence of multibyte characters into a sequence of corresponding wide-character codes.

## Format

> #include <stdlib.h>

> size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);

## Arguments

> ### pwcs

> A pointer to the array containing the resulting sequence of wide-character codes.

> ### s

> A pointer to the array of multibyte characters.

> ### n

> The maximum number of wide-character codes that can be stored in the array pointed to by pwcs.

## Description

> This function converts a sequence of multibyte characters from the array pointed to by s to a sequence of wide-character codes that are stored into the array pointed to by pwcs, up to a maximum of n codes.

> This function is affected by the LC_CTYPE category of the program's current locale. If copying takes place between objects that overlap, the behavior is undefined.

## Return Values

> x | The number of array elements modified or required, not included any terminating zero code. The array will not be zero-terminated if the value returned is n. If pwcs is the NULL pointer, `mbstowcs` returns the number of elements required for the wide-character array.
> ( `size_t` ) --1 | Indicates that an error occurred. The function sets `errno` to EILSEQ - Invalid character detected.

# mbtowc

> Converts a multibyte character to its wide-character equivalent.

## Format

> #include <stdlib.h>

> int mbtowc (wchar_t *pwc, const char *s, size_t n);

## Arguments

> ### pwc

> A pointer to the resulting wide-character code.

> ### s

> A pointer to the multibyte character.

> ### n

> The maximum number of bytes that comprise the next multibyte character.

## Description

> If the character is n or fewer bytes, this function converts the multibyte character pointed to by s to its wide-character equivalent. If the character is invalid or greater than n bytes, the function returns --1 to indicate an error.

> If pwc is a NULL pointer and s is not a null pointer, the function determines the number of bytes that constitute the multibyte character pointed to by s (regardless of the value of n).

> This function is affected by the LC_CTYPE category of the program's current locale.

## Return Values

> x | The number of bytes that comprise the valid character pointed to by s.
> 0 | If s is either a NULL pointer or a pointer to the null byte.
> --1 | Indicates an error occurred. The function sets `errno` to EILSEQ -- Invalid character detected.

# mbsinit

> Determines whether an `mbstate_t` object decribes an initial conversion state.

## Format

> #include <wchar.h>

> int mbsinit (const mbstate_t *ps);

## Arguments

> ### ps

> A pointer to the `mbstate_t` object. `mbstate_t` is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

## Description

> If ps is not a NULL pointer, this function determines whether the `mbstate_t` object pointed to by ps describes an initial conversion state. A zero `mbstate_t` object always describes an initial conversion state.

## Return Values

> nonzero | The ps argument is a NULL pointer, or the `mbstate_t` object pointed to by ps describes an initial conversion state.
> 0 | The `mbstate_t` object pointed to by ps does not describe an initial conversion state.

# mbsrtowcs

> Converts a sequence of multibyte characters to a sequence of corresponding wide-character codes.

## Format

> #include <wchar.h>

> size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len, mbstate_t *ps);

Function Variants This function also has variants named `_mbsrtowcs32` and `_mbsrtowcs64` 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

> ### dst

> A pointer to the destination array containing the resulting sequence of wide-character codes.

> ### src

> An address of the pointer to an array containing a sequence of multibyte characters to be converted.

> ### len

> The maximum number of wide character codes that can be stored in the array pointed to by dst.

> ### ps

> A pointer to the `mbstate_t` object. If a NULL pointer is specified, the function uses its internal `mbstate_t` object. `mbstate_t` is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

## Description

> This function converts a sequence of multibyte characters, beginning in the conversion state described by the object pointed to by ps, from the array indirectly pointed to by src, into a sequence of corresponding wide characters.

> If dst is not a NULL pointer, the converted characters are stored into the array pointed to by dst. Conversion continues up to and including a terminating null character, which is also stored.

> Conversion stops earlier for one of the following reasons:

> - A sequence of bytes is encountered that does not form a valid multibyte character.
> - If dst is not a NULL pointer, when len codes have been stored into the array pointed to by dst.

> If dst is not a NULL pointer, the pointer object pointed to by src is assigned either a NULL pointer, (if the conversion stopped because of reaching a terminating null wide character) or the address just beyond the last multibyte character converted (if any). If conversion stopped because of reaching a terminating null wide character, the resulting state described is the initial conversion state.

## Return Values

> n | The number of multibyte characters successfully converted, sequence, not including the terminating null (if any).
> --1 | Indicates an error. A sequence of bytes that do not form valid multibyte character was encountered. `errno` is set to EILSEQ; the conversion state is undefined.

Previous | Next | Contents | Index

privacy and legal statement