HP OpenVMS Systems

int sscanf(const char *s, const char *format, ...);

Equivalent to the fscanf function except that the argument s specifies a string, rather than a stream, from which the input will be read. Reaching the end of the string is equivalent to the fscanf function encountering end-of-file. If copying takes place between objects that overlap, the behavior is undefined.

#include <stdarg.h>
int vfprintf(FILE *stream, const char *format, va_list arg);

Equivalent to the fprintf function with the variable argument list replaced by arg, which must have been initialized by the va_start macro (and possibly subsequent va_arg calls). The vfprintf function does not invoke the va_end macro.

#include <stdarg.h>
int vprintf(const char *format, va_list arg);

Equivalent to the printf function with the variable argument list replaced by arg, which must have been initialized by the va_start macro (and possibly subsequent va_arg calls). The vprintf function does not invoke the va_end macro.

#include <stdarg.h>
int vsprintf(char *s, const char *format, va_list arg);

Equivalent to the sprintf function with the variable argument list replaced by arg, which must have been initialized by the va_start macro (and possibly subsequent va_arg calls). The vsprintf function does not invoke the va_end macro.

Character Input/Output Functions

int fgetc(FILE *stream);

Returns the next character (if there is one) as an unsigned char converted to an int , from the input stream pointed to by stream, and advances the associated file-position indicator for the stream (if defined). If the stream is at end-of-file, the end-of-file indicator for the stream is set, and fgetc returns EOF . If a read error occurs, the error indicator is set, and fgetc returns EOF .

char *fgets(char *s, int n, FILE *stream);

Reads at most one less than the number of characters specified by n from the stream pointed to by stream into the array pointed to by s. No additional characters are read after a new-line character (which is retained) or after the end-of-file. A null character is written immediately after the last character read into the array.
The fgets function returns s if successful. If the end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

int fputc(int c, FILE *stream);

Writes the character c (converted to an unsigned char ) to the output stream pointed to by stream, at the position indicated by the associated file position indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the output stream. The fputc function returns the character written. If a write error occurs, the error indicator for the stream is set, and fputc returns EOF .

int fputs(const char *s, FILE *stream);

Writes the string pointed to by s to the stream pointed to by stream. The terminating null character is not written.
The fputs function returns EOF if a write error occurs. Otherwise, it returns a nonnegative value.

int getc(FILE *stream);

Equivalent to the fgetc function, but if it is implemented as a macro it can evaluate stream more than once. For this reason, the argument should never be an expression with side effects.

int getchar(void);

Equivalent to the getc function with the argument stdin .

char *gets(char *s);

Reads characters from the input stream pointed to by stdin into the array pointed to by s, until the end-of-file is encountered or a new-line character is read. Any new-line character is discarded, and a null character is written immediately after the last character read into the array.
The fgets function returns s if successful. If the end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

int putc(int c, FILE *stream);

Equivalent to the fputc function, but if it is implemented as a macro it can evaluate stream more than once. For this reason the argument should never be an expression with side effects.

int putchar(int c);

Equivalent to the putc function with the second argument stdout .

int puts(const char s);

Writes the string pointed to by s to the stream pointed to by stdout , and appends a new-line character to the output. The terminating null character is not written. The puts function returns EOF if a write error occurs. Otherwise, it returns a nonnegative value.

int ungetc(int c, FILE *stream);

Pushes a character c (converted to an unsigned char ) back into the input stream pointed to by stream, and leaves the stream positioned before the character. The pushed back characters are returned by subsequent reads on that stream in the reverse order of their pushing. A successful intervening call to a file positioning function for that stream ( fseek , fsetpos , or rewind ) discards any pushed-back characters.
One pushback is guaranteed, even if there has been no previous activity on the file. The ungetc function returns the converted pushed-back character, or it returns EOF if the operation fails.

Direct Input/Output Functions

size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);

Reads into the array pointed to by ptr up to nmemb elements of size size from the stream pointed to by stream. The file-position indicator for the stream (if defined) is advanced by the number of characters successfully read. If an error occurs, the resulting value of the file-position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.
The fread function returns the number of elements successfully read, which may be less than nmemb if a read error or end-of-file is encountered. If size or nmemb is 0, fread returns 0, and the contents of the array and the state of the stream are unchanged.

size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);

Writes from the array pointed to by ptr up to nmemb elements of size size to the stream pointed to by stream. The file-position indicator for the stream (if defined) is advanced by the number of characters successfully written. If an error occurs, the resulting value of the file-position indicator for the stream is indeterminate.
The fwrite function returns the number of elements successfully written, which is less than nmemb only if a write error is encountered.

File Positioning Functions

int fgetpos(FILE *stream, fpos_t *pos);

Stores the current value of the file-position indicator for the stream pointed to by stream into the object pointed to by pos. The value stored contains unspecified information used by the fsetpos function to return the stream to its position at the time of the call to fgetpos .
If successful, the fgetpos function returns 0. On failure, fgetpos returns nonzero and stores an implementation-defined positive value in errno .

int fseek(FILE *stream, long int offset, int whence);

Sets the file-position indicator to the specified byte offset in the stream pointed to by stream.
For a binary stream, the new position, measured in characters from the beginning of the file, is obtained by adding offset to the position specified by whence, which is one of the following:

• The beginning of the file if whence is SEEK_SET
• The current value of the file-position indicator if whence is SEEK_CUR
• The end of the file if whence is SEEK_END

For a text stream, either offset is 0 or it is a value returned by an earlier call to the ftell function on the same stream and whence is SEEK_SET .
A successful call to fseek clears the end-of-file indicator for the stream and reverses any effects of the ungetc function on the same stream. After an fseek call, the next operation on an update stream can be either input or output. The fseek function returns nonzero only for a request that cannot be satisfied.

int fsetpos(FILE *stream, const fpos_t *pos);

Sets the file-position indicator for the stream pointed to by stream according to the value of the object pointed to by pos, which is a value obtained from an earlier call to the fgetpos function on the same stream.
A successful call to fsetpos clears the end-of-file indicator for the stream and reverses any effects of the ungetc function on the same stream. After an fsetpos call, the next operation on an update stream can be either input or output.
If successful, the fsetpos function returns 0. On failure, fsetpos returns nonzero and stores an implementation-defined positive value in errno .

long int ftell(FILE *stream);

Gets the current value of the file-position indicator for the stream pointed to by stream. For a binary stream, the value is the number of characters from the beginning of the file. For a text stream, its file-position indicator contains unspecified information used by the fseek function for returning the file-position indicator for the stream to its position at the time of the call to ftell . The difference between two such return values is not necessarily a meaningful measure of the number of characters written or read.
If successful, the ftell function returns the current value of the file-position indicator for the stream. On failure, ftell returns - 1L and stores an implementation-defined positive value in errno .

void rewind(FILE *stream);

Sets the file-position indicator for the stream pointed to by stream to the beginning of the file. It is equivalent to the following, except that the error indicator for the stream is also cleared:

(void)fseek(stream, 0L, SEEK_SET)

The rewind function returns no value.

Error-Handling Functions

void clearerr(FILE *stream);

Clears the end-of-file and error indicators for the stream pointed to by stream. The clearerr function returns no value.

int feof(FILE *stream);

Tests the end-of-file indicator for the stream pointed to by stream. The feof function returns nonzero only if the end-of-file indicator is set for stream .

int ferror(FILE *stream);

Tests the error indicator for the stream pointed to by stream. The ferror function returns nonzero only if the end-of-file indicator is set for stream .

void perror(const char *s);

Maps the error number in the integer expression errno to an error message. It writes the following sequence of characters to the standard error stream:

1. The string pointed to by s followed by a colon (:) and a space (if s is not a null pointer and the character pointed to by s is not the null character)
2. An appropriate error message string followed by a new-line character

The contents of the error message strings are the same as those returned by the strerror function with argument errno , which are implementation-defined. The perror function returns no value.

9.14 General Utilities (<stdlib.h>)

The <stdlib.h> header file declares four types and several functions of general use, and defines several macros. The functions perform string conversion, random number generation, searching and sorting, memory management, and similar tasks.

Types

size_t

An unsigned integral type of the result of the sizeof operator.

wchar_t

An integral type whose range of values can represent distinct codes for all members of the largest extended character set specified among the supported locales.

div_t

A structure type that is the type of the value returned by the div function.

ldiv_t

A structure type that is the type of the value returned by the ldiv function.

Macros

NULL

Expands to an implementation-defined null pointer constant.

EXIT_FAILURE / EXIT_SUCCESS

Expand to integral expressions for use as the argument to the exit function to return unsuccessful or successful termination status, respectively, to the host environment. These macros are useful as return values from the main function as well.

RAND_MAX

Expands to an integral constant expression whose value is the maximum value returned by the rand function.

MB_CUR_MAX

Expands to a positive integer expression whose value is the maximum number of bytes in a multibyte character for the extended character set specified by the current locale (category LC_TYPE ), and whose value is never greater than MB_LEN_MAX .

String Conversion Functions

double atof(const char *nptr);

Converts the string pointed to by nptr to double representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

strtod(nptr, (char **)NULL)

int atoi(const char *nptr);

Converts the string pointed to by nptr to int representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

(int)strtol(nptr, (char **)NULL, 10)

long int atol(const char *nptr);

Converts the string pointed to by nptr to long int representation and returns the converted value. Except for its behavior when an error occurs, this function is equivalent to:

strtol(nptr, (char **)NULL, 10)

double strtod(const char *nptr, char **endptr);

Converts the string pointed to by nptr to double representation.
See your HP C library routine documentation for a detailed description of this function.

long int strtol(const char *nptr, char **endptr, int base);

Converts the string pointed to by nptr to long int representation.
See your HP C library routine documentation for a detailed description of this function.

unsigned long int strtoul(const char *nptr, char **endptr, int base);

Converts the string pointed to by nptr to unsigned long int representation.
See your HP C library routine documentation for a detailed description of this function.

Pseudo-Random Sequence Generation Functions

int rand(void);

Returns a sequence of pseudo-random integers in the range 0 to RAND_MAX .

void srand(unsigned int seed);

Uses the argument as a seed for a new sequence of pseudo-random integers to be returned by subsequent calls to rand . If srand is then called with the same seed value, the sequence of pseudo-random integers is repeated. If rand is called before any calls to srand are made, the sequence generated is the same as when srand is first called with a seed value of 1. The srand function returns no value.

Memory Management Functions

void *calloc(size_t nmemb, size_t size);

Allocates an area in memory for an array of nmemb items, each with size size. The area is initialized to all bits 0. The calloc function returns either a null pointer if unable to allocate, or a pointer to the allocated area.

void free(void *ptr);

Deallocates the memory area pointed to by ptr that was allocated by a previous calloc , malloc , or realloc . If ptr is null, no action occurs. No value is returned.

void *malloc(size_t size);

Allocates a contiguous area in memory for an object of size size. The area is not initialized. This function returns a pointer to the allocated area, or it returns a null pointer if unable to allocate.

void *realloc(void *ptr, size_t size);

Changes the size of the area pointed to by ptr to the number of bytes specified by size. If ptr is null, the behavior of realloc is identical to malloc . The contents of the area are unchanged up to the lesser of the old and new sizes. This function returns either a null pointer if unable to resize, or a pointer to the possibly moved reallocated area.

Communication with the Environment

void abort(void);

Causes abnormal program termination to occur, unless the SIGABRT signal is being caught and the signal handler does not return. The abort function cannot return to its caller.

int atexit(void (*func)(void));

Registers the function pointed to by func to be called without arguments at normal program termination. Up to 32 functions can be registered. The atexit function returns 0 if the registration succeeds; otherwise, it returns nonzero.

void exit(int status);

Causes normal program termination to occur. If a program executes more than one call to exit , the behavior is undefined. Upon execution, the following occurs:

1. All functions registered by atexit are called in the reverse order of their registration.
2. All open output streams are flushed, all open streams are closed, and all files created by tmpfile are removed.
3. Control is returned to the host environment. The value of status corresponds to an errno value:
   • If the value status is 0 or EXIT_SUCCESS , a successful termination status is returned.
   • If the value status is EXIT_FAILURE , an unsuccessful termination status is returned.
   • Otherwise, an unsuccessful termination status is returned.

char *getenv(const char *name);

Searches an environment list provided by the host environment.
See your HP C library routine documentation for a detailed description of this function.

int *system(const char *string);

Passes the string pointed to by string to the host environment for execution by a command processor. A null pointer can be specified to inquire whether a command processor exists. If the argument is a null pointer, the system function returns nonzero if a command processor is available or 0 if one is not available. If the argument is not a null pointer, the return value is the status returned by the command processor or 0 if a command processor is not available.
See your HP C library routine documentation for a detailed description of this function.