HP OpenVMS Systems

Same as putc , except used only within a scope protected by flockfile and funlockfile .

Format

#include <stdio.h>

int putc_unlocked (int character, FILE *file_ptr);

Argument

character

The character to be written.

file_ptr

A file pointer to the output stream.

Description

The reentrant version of the putc macro is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the stream. The unlocked version of this call, putc_unlocked can be used to avoid the overhead. The putc_unlocked macro is functionally identical to the putc macro, except that it is not required to be implemented in a thread-safe manner. The putc_unlocked macro can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before putc_unlocked is used.

Since putc_unlocked is a macro, a file pointer argument with side effects might be evaluated incorrectly. In such a case, use the fputc_unlocked function instead.

See also flockfile , ftrylockfile , and funlockfile .

Return Values

x	The character written to the file. Indicates success.
EOF	Indicates the end-of-file or an error.

Writes a single character to the standard output ( stdout ) and returns the character.

Format

#include <stdio.h>

int putchar (int character);

Argument

character

An object of type int .

Description

The putchar function is identical to fputc (character, stdout ).

Return Values

character	Indicates success.
EOF	Indicates output errors.

Same as putchar , except used only within a scope protected by flockfile and funlockfile .

Format

#include <stdio.h>

int putchar_unlocked (int character);

Argument

character

An object of type int .

Description

The reentrant version of the putchar function is locked against multiple threads calling it simultaneously. This incurs overhead to ensure integrity of the output stream. The unlocked version of this call, putchar_unlocked can be used to avoid the overhead. The putchar_unlocked function is functionally identical to the putchar function, except that it is not required to be implemented in a thread-safe manner. The putchar_unlocked function can be safely used only within a scope that is protected by the flockfile and funlockfile functions used as a pair. The caller must ensure that the stream is locked before putchar_unlocked is used.

See also flockfile , ftrylockfile , and funlockfile .

Return Values

x	The next character from stdin , converted to int .
EOF	Indicates the end-of-file or an error.

Sets an environmental variable.

Format

#include <stdlib.h>

int putenv (const char *string);

Argument

string

A pointer to a name=value string.

Description

The putenv function sets the value of an environment variable by altering an existing variable or by creating a new one. The string argument points to a string of the form name=value, where name is the environment variable and value is the new value for it.

The string pointed to by string becomes part of the environment, so altering the string changes the environment. When a new string-defining name is passed to putenv , the space used by string is no longer used.

Notes The putenv function manipulates the environment pointed to by the environ external variable, and can be used with getenv . However, the third argument to the main function (the environment pointer), is not changed. The putenv function uses the malloc function to enlarge the environment. A potential error is to call putenv with an automatic variable as the argument, then exit the calling function while string is still part of the environment. Do not use the setenv , getenv , and putenv functions to manipulate symbols and logicals. Instead, use the OpenVMS library calls lib$set_logical , lib$get_logical , lib$set_symbol , and lib$get_symbol . The * env functions deliberately provide UNIX behavior, and are not a substitute for these OpenVMS runtime library calls. OpenVMS DCL symbols, not logical names, are the closest analog to environment variables on UNIX systems. While getenv is a mechanism to retrieve either a logical name or a symbol, it maintains an internal cache of values for use with setenv and subsequent getenv calls. The setenv function does not write or create DCL symbols or OpenVMS logical names. This is consistent with UNIX behavior. On UNIX systems, setenv does not change or create any symbols that will be visible in the shell after the program exits.

Return Values

0	Indicates success.
- 1	Indicates an error. errno is set to ENOMEM---Not enough memory available to expand the environment list.

Restriction

The putenv function cannot take a 64-bit address. See Section 1.10.

Writes a character string to the standard output ( stdout ) followed by a new-line character.

Format

#include <stdio.h>

int puts (const char *str);

Argument

str

A pointer to a character string.

Description

The puts function does not copy the terminating null character to the output stream.

Return Values

Nonnegative value	Indicates success.
EOF	Indicates output errors.

Writes characters to a specified file.

Format

#include <stdio.h>

int putw (int integer, FILE *file_ptr);

Arguments

integer

An object of type int or long .

file_ptr

A file pointer.

Description

The putw function writes four characters to the output file as an int . No conversion is performed.

Return Values

integer	Indicates success.
EOF	Indicates output errors.

Converts a wide character to its corresponding multibyte value, and writes the result to a specified file.

Format

#include <wchar.h>

wint_t putwc (wint_t wc, FILE *file_ptr);

Arguments

wc

An object of type wint_t .

file_ptr

A file pointer.

Description

Since putwc might be implemented as a macro, a file pointer argument with side effects (for example putwc (wc, *f++) ) might be evaluated incorrectly. In such a case, use the fputwc function instead.

See also fputwc .

Return Values

x	The character written to the file. Indicates success.
WEOF	Indicates an output error. The function sets errno . For a list of the errno values set by this function, see fputwc .

Writes a wide character to the standard output ( stdout ) and returns the character.

Format

#include <wchar.h>

wint_t putwchar (wint_t wc);

Arguments

wc

An object of type wint_t .

Description

The putwchar function is identical to fputwc (wc, stdout ).

Return Values

x	The character written to the file. Indicates success.
WEOF	Indicates an output error. The function sets errno . For a list of the errno values set by this function, see fputwc .

Writes into a given position within a file without changing the file pointer.

Format

#include <unistd.h>

ssize_t pwrite (int file_desc, const void *buffer, size_t nbytes, off_t offset);

Arguments

file_desc

A file descriptor that refers to a file currently opened for writing or updating.

buffer

The address of contiguous storage from which the output data is taken.

nbytes

The maximum number of bytes involved in the write operation.

offset

The offset for the desired position inside the file.

Description

The pwrite function performs the same action as write , except that it writes into a given position in the file without changing the file pointer. The first three arguments to pwrite are the same as for write , with the addition of a fourth argument offset for the desired position inside the file.

Return Values

n	The number of bytes written.
- 1	Upon failure, the file pointer remains unchanged and pwrite sets errno to one of the following values: EINVAL -- The offset argument is invalid. The value is negative. ESPIPE -- fildes is associated with a pipe or FIFO.

Returns the absolute value of an integer as an __int64 . llabs is a synonym for qabs .

Format

#include <stdlib.h>

__int64 qabs (__int64 j);

__int64 llabs (__int64 j);

Argument

j

A value of type __int64 .

Returns the quotient and the remainder after the division of its arguments. lldiv is a synonym for qdiv .

Format

#include <stdlib.h>

qdiv_t qdiv (__int64 numer, __int64 denom);

lldiv_t lldiv (__int64 numer, __int64 denom);

Arguments

numer

A numerator of type __int64 .

denom

A denominator of type __int64 .

Description

The types qdiv_t and lldiv_t are defined in the <stdlib.h> header file as follows:

typedef struct { __int64 quot, rem; } qdiv_t, lldiv_t;

Sorts an array of objects in place. It implements the quick-sort algorithm.

Format

#include <stdlib.h>

void qsort (void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

Arguments

base

A pointer to the first member of the array. The pointer should be of type pointer-to-element and cast to type pointer-to-character.

nmemb

The number of objects in the array.

size

The size of an object, in bytes.

compar

A pointer to the comparison function.

Description

Two arguments are passed to the comparison function pointed to by compar. The two arguments point to the objects being compared. Depending on whether the first argument is less than, equal to, or greater than the second argument, the comparison function returns an integer less then, equal to, or greater than 0.

The comparison function compar need not compare every byte, so arbitrary data might be contained in the objects in addition to the values being compared.

The order in the output of two objects that compare as equal is unpredictable.

Generates a specified software signal. Generating a signal causes the action routine established by the signal , ssignal , or sigvec function to be invoked.

Format

#include <signal.h>

int raise (int sig); (ANSI C)

int raise (int sig[, int sigcode]); (HP C EXTENSION)

Arguments

sig

The signal to be generated.

sigcode

An optional signal code, available only when not compiling in strict ANSI C mode. For example, signal SIGFPE---the arithmetic trap signal---has 10 different codes, each representing a different type of arithmetic trap.

The signal codes can be represented by mnemonics or numbers. The arithmetic trap codes are represented by the numbers 1 to 10; the SIGILL codes are represented by the numbers 0 to 2. The code values are defined in the <signal.h> header file. See Tables 4-4 and 4-5 for a list of signal mnemonics, codes, and corresponding OpenVMS exceptions.

Description

Calling the raise function has one of the following results:

• If raise specifies a sig argument that is outside the range defined in the <signal.h> header file, then the raise function returns 0, and the errno variable is set to EINVAL.
• If signal , ssignal , or sigvec establishes SIG_DFL (default action) for the signal, then the functions do not return. The image is exited with the OpenVMS error code corresponding to the signal.
• If signal , ssignal , or sigvec establishes SIG_IGN (ignore signal) as the action for the signal, then raise returns its argument, sig.
• signal , ssignal , or sigvec must establish an action function for the signal. That function is called and its return value is returned by raise .

See Chapter 4 for more information on signal processing.

See also gsignal , signal , ssignal , and sigvec .

Return Values

0	If successful.
nonzero	If unsuccessful.

Returns pseudorandom numbers in the range 0 to 2³¹ - 1.

Format

#include <math.h>

int rand (void);

int rand_r (unsigned int seed); (ALPHA, I64)

Argument

seed

An initial seed value.

Description

The rand function computes a sequence of pseudorandom integers in the range 0 to {RAND_MAX} with a period of at least 2³².

The rand_r function computes a sequence of pseudorandom integers in the range 0 to {RAND_MAX}. The value of the {RAND_MAX} macro will be at least 32767.

If rand_r is called with the same initial value for the object pointed to by seed and that object is not modified between successive returns and calls to rand_r , the same sequence is generated.

See also srand .

For other random-number algorithms, see random and all the * 48 functions.

Return Value

n	A pseudorandom number.

Generates pseudorandom numbers in a more random sequence.

Format

#include <stdlib.h>

long int random (void);

Description

The random function is a random-number generator that has virtually the same calling sequence and initialization properties as the rand function, but produces sequences that are more random. The low 12 bits generated by rand go through a cyclic pattern. All bits generated by random are usable. For example, random () &1 produces a random binary value.

The random function uses a nonlinear, additive-feedback, random-number generator employing a default state-array size of 31 integers to return successive pseudorandom numbers in the range from 0 to 2³¹-1 . The period of this random-number generator is approximately 16*( 2³¹-1 ). The size of the state array determines the period of the random-number generator. Increasing the state array size increases the period.

With a full 256 bytes of state information, the period of the random-number generator is greater than 2⁶⁹ , and is sufficient for most purposes.

Like the rand function, the random function produces by default a sequence of numbers that you can duplicate by calling the srandom function with a value of 1 as the seed. The srandom function, unlike the srand function, does not return the old seed because the amount of state information used is more than a single word.

See also rand , srand , srandom , setstate , and initstate .

Return Value

n	A random number.