DEC C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index

The addch routine performs the same function as waddch , but on the stdscr window.

The cursor is moved after the character is written to the screen.


Return Values

OK Indicates success.
ERR Indicates that writing the character would cause the screen to scroll illegally. For more information, see the scrollok function in this section.

[w]addstr

Add the string pointed to by str to the window at the current position of the cursor.

Format

#include <curses.h>

int addstr (char *str);

int waddstr (WINDOW *win, char *str);


ARGUMENTS

win

A pointer to the window.

str

A pointer to a character string.

DESCRIPTION

When the waddstr function is used on a subwindow, the string is written onto the underlying window as well.

The addstr routine performs the same function as waddstr , but on the stdscr window.

The cursor position changes as a result of calling this routine.


Return Values

OK Indicates success.
ERR Indicates that the function causes the screen to scroll illegally, but it places as much of the string onto the window as possible. For more information, see the scrollok function in this section.

alarm

Sends the signal SIGALRM (defined in the <signal.h> header file) to the invoking process after the number of seconds indicated by its argument has elapsed.

Format

#include <unistd.h>

unsigned int alarm (unsigned int seconds);

(ISO POSIX-1) int alarm (unsigned int seconds);

(COMPATABILITY)


ARGUMENT

seconds

Has a maximum limit of LONG_MAX seconds.

DESCRIPTION

Calling the alarm function with a 0 argument cancels any pending alarms.

Unless it is caught or ignored, the signal generated by alarm terminates the process. Successive alarm calls reinitialize the alarm clock. Alarms are not stacked.

Because the clock has a 1-second resolution, the signal may occur up to 1 second early. If the SIGALRM signal is caught, resumption of execution may be held up due to scheduling delays.

When the SIGALRM signal is generated, a call to SYS$WAKE is generated whether or not the process is hibernating. The pending wake causes the current pause () to return immediately (after completing any function that catches the SIGALRM).


Return Value

n The number of seconds remaining from a previous alarm request.

asctime

Converts a broken-down time (see the localtime function for more information) into a 26-character string in the following form:


Sun Sep 16 01:03:52 1984\n\0 

All fields have a constant width.

This function is nonreentrant.


Format

#include <time.h>

char *asctime (const struct tm *timeptr);


ARGUMENT

timeptr

A pointer to a structure of type tm , which contains the broken-down time.

DESCRIPTION

See the <time.h> header file for a description of the tm structure.

The asctime function converts the contents of tm into a 26-character string, as shown in the previous example, and returns a pointer to the string. Subsequent calls to asctime or ctime may point to the same static string, which is overwritten by each call.

See the localtime function in this section for a list of the members in tm .


Return Value

x A pointer to the string.

asin

Returns a value in the range --<pi symbol>/2 to <pi symbol>/2, which is the arc sine of its radian argument.

Format

#include <math.h>

double asin (double x);


ARGUMENT

x

A radian expressed as a real number.

DESCRIPTION

When abs (x) is greater than 1.0, the value of asin (x) is 0 and errno is set to EDOM.

assert

Used for implementing run-time diagnostics in programs.

Format

#include <assert.h>

void assert (int expression);


ARGUMENT

expression

An expression that has an int type.

DESCRIPTION

When assert is executed, if expression is false (that is, it evaluates to 0), assert writes information about the particular call that failed (including the text of the argument, the name of the source file, and the source line number; the latter two are respectively the values of the preprocessing macros __FILE__ and __LINE__) to the standard error file in an implementation-defined format. Then, it calls the abort function.

The assert function writes a message in the following form:


Assertion failed:  expression, file aaa, line nnn

If expression is true (that is, it evaluates to nonzero) or if the signal SIGABRT is being ignored, assert returns no value.

Note

If a null character ('\0') is part of the expression being asserted, then only the text up to and including the null character is printed, since the null character effectively terminates the string being output.

Compiling with the CC command qualifier /DEFINE=NDEBUG or with the preprocessor directive #define NDEBUG ahead of the #include assert statement causes the assert function to have no effect.


Example


#include <stdio.h> 
#include <assert.h> 
 
main() 
{ 
   printf("Only this and the assert\n"); 
   assert( 1==2 );    /* expression is FALSE */ 
 
   /* abort should be called so the printf will not happen. */ 
 
   printf("FAIL abort did not execute"); 
} 


atan

Returns a value in the range --<pi symbol>/2 to <pi symbol>/2, which is the arc tangent of its radian argument.

Format

#include <math.h>

double atan (double x);


ARGUMENT

x

A radian expressed as a real value.

atan2

Returns a value in the range --<pi symbol> to <pi symbol>. The returned value is the arc tangent of y/x, where y and x are the two arguments.

Format

#include <math.h>

double atan2 (double y, double x);


ARGUMENTS

y

A real value.

x

A real value.

atexit

Registers a function that is called without arguments at program termination.

Format

#include <stdlib.h>

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


ARGUMENT

func

A pointer to the function to be registered.

Return Values

0 Indicates that the registration has succeeded.
nonzero Indicates failure.

RESTRICTION

The longjmp function cannot be executed from within the handler, because the destination address of the longjmp no longer exists.

Example


#include <stdlib.h> 
#include <stdio.h> 
 
static void hw(void); 
 
main() 
{ 
    atexit(hw); 
} 
    
static void hw() 
{ 
        puts("Hello, world\n"); 
} 

Running this example produces the following output:


Hello, world 
 


atof

Converts an ASCII character string to a double-precision number.

Format

#include <stdlib.h>

double atof (const char *nptr);


ARGUMENT

nptr

A pointer to the character string to be converted to a double-precision number. The string is interpreted by the same rules that are used to interpret floating constants.

DESCRIPTION

The string to be converted has the following format:

[white-spaces][+|-]digits[radix-character][digits][e|E[+|-]integer]

Where radix-character is defined in the current locale.

The first unrecognized character ends the conversion.

This function is equivalent to strtod(nptr, (char**) null) .


Return Values

x The converted value.
0 Indicates an underflow or the conversion could not be performed. The function sets errno to ERANGE or EINVAL, respectively.
(+/-)HUGE_VAL Indicates overflow; errno is set to ERANGE.

atoi, atol

Convert strings of ASCII characters to the appropriate numeric values.

Format

#include <stdlib.h>

int atoi (const char *nptr);

long int atol (const char *nptr);


ARGUMENT

nptr

A pointer to the character string to be converted to a numeric value.

DESCRIPTION

The atoi and atol functions convert the initial portion of a string to its decimal int or long int value, respectively. The atoi and atol functions do not account for overflows resulting from the conversion. The string to be converted has the following format:

[white-spaces][+|-]digits

The function call atol (str) is equivalent to strtol (str, (char**)null, 10) , and the function call atoi (str) is equivalent to (int) strtol (str, (char**)null, 10) , except, in both cases, for the behavior on error.


Return Value

n The converted value.

atoq, atoll (ALPHA ONLY)

Convert strings of ASCII characters to the appropriate numeric values. atoll is a synonym for atoq .

Format

#include <stdlib.h>

__int64 atoq (const char *nptr);

__int64 atoll (const char *nptr);


ARGUMENT

nptr

A pointer to the character string to be converted to a numeric value.

DESCRIPTION

The atoq (or atoll ) function converts the initial portion of a string to its decimal __int64 value. This function does not account for overflows resulting from the conversion. The string to be converted has the following format:

[white-spaces][+|-]digits

The function call atoq (str) is equivalent to strtoq (str, (char**)null, 10) , except for the behavior on error.


Return Value

n The converted value.

basename

Returns the last component of a path name.

Format

#include <libgen.h>

char *basename (char *path);

Function Variants This function also has variants named _basename32 and _basename64 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

path

A UNIX style pathname from which the base path name is extracted.

DESCRIPTION

This function takes the UNIX style pathname pointed to by path and returns a pointer to the pathname's final component, deleting any trailing slash (/) characters.

If path consists entirely of the slash (/) character, the function returns a pointer to the string "/".

If path is a NULL pointer or points to an empty string, the function returns a pointer to the string ".".

The basename function can modify the string pointed to by path.


Return Values

x A pointer to the final component of path.
"/" If path consists entirely of the '/' character.
"." If path is a NULL pointer or points to an empty string.

bcmp

Compares byte strings.

Format

#include <strings.h>

void bcmp (const void *string1, const void *string2, size_t length);


ARGUMENTS

string1, string2

The byte strings to be compared.

length

The length (in bytes) of the strings.

DESCRIPTION

The bcmp function compares the byte string in string1 against the byte string in string2.

Unlike the string functions, there is no checking for null bytes. Zero-length strings are always identical.

Note that bcmp is equivalent to memcmp , which is defined by the ANSI C Standard. Therefore, using memcmp is recommended for portable programs.


Return Values

0 The strings are identical.
Nonzero The strings are not identical.

bcopy

Copies byte strings.

Format

#include <strings.h>

void bcopy (const void *source, void *destination, size_t length);


ARGUMENTS

source

Pointer to the source string.

destination

Pointer to the destination string.

length

The length (in bytes) of the string.

DESCRIPTION

The bcopy function operates on variable-length strings of bytes. It copies the value of the length argument in bytes from the string in the source argument to the string in the destination argument.

Unlike the string functions, there is no checking for null bytes. If the length argument is 0 (zero), no bytes are copied.

Note that bcopy is equivalent to memcpy , which is defined by the ANSI C Standard. Therefore, using memcpy is recommended for portable programs.


box

Draws a box around the window using the character vert as the character for drawing the vertical lines of the rectangle, and hor for drawing the horizontal lines of the rectangle.

Format

#include <curses.h>

int box (WINDOW *win, char vert, char hor);


ARGUMENTS

win

The address of the window.

vert

The character for the vertical edges of the window.

hor

The character for the horizontal edges of the window.

DESCRIPTION

This function copies boxes drawn on subwindows onto the underlying window. Use caution when using functions such as overlay and overwrite with boxed subwindows. Such functions copy the box onto the underlying window.

Return Values

OK Indicates success.
ERR Indicates an error.

brk

Determines the lowest virtual address that is not used with the program.

Format

#include <stdlib.h>

void *brk (unsigned long int addr);


ARGUMENT

addr

The lowest address, which the function rounds up to the next multiple of the page size. This rounded address is called the break address.

DESCRIPTION

An address that is greater than or equal to the break address and less than the stack pointer is considered to be outside the program's address space. Attempts to reference it will cause access violations.

When a program is executed, the break address is set to the highest location defined by the program and data storage areas. Consequently, brk is needed only by programs that have growing data areas.


Return Values

n The new break address.
(void *)(--1) Indicates that the program is requesting too much memory. errno and vaxc$errno are updated.

RESTRICTION

Unlike other C library implementations, the DEC C RTL memory allocation functions (such as malloc ) do not rely on brk or sbrk to manage the program heap space. Consequently, on OpenVMS systems, calling brk or sbrk can interfere with memory allocation routines. The brk and sbrk functions are provided only for compatibility purposes.

bsearch

Performs a binary search. It searches an array of sorted objects for a specified object.

Format

#include <stdlib.h>

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

Function Variants This function also has variants named _bsearch32 and _bsearch64 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

key

A pointer to the object to be sought in the array. This pointer should be of type pointer-to-object and cast to type pointer-to-void.

base

A pointer to the initial member of the array. This pointer should be of type pointer-to-object and cast to type pointer-to-void.

nmemb

The number of objects in the array.

size

The size of an object, in bytes.

compar

A pointer to the comparison function.

DESCRIPTION

The array must first be sorted in increasing order according to the specified comparison function pointed to by compar.

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 must return an integer less than, equal to, or greater than 0.

It is not necessary for the comparison function (compar) to compare every byte in the array. Therefore, the objects in the array can contain arbitrary data in addition to the data being compared.

Since it is declared as type pointer-to-void, the value returned must be cast or assigned into type pointer-to-object.


Return Values

x A pointer to the matching member of the array or a null pointer if no match is found.
NULL Indicates that the key cannot be found in the array.

Example


#include <stdio.h> 
#include <stdlib.h> 
 
#define SSIZE 30 
 
extern int compare();   /* function prototype for comparison function */ 
 
int array[SSIZE] = {30, 1, 29, 2, 28, 3, 27, 4, 26, 5, 24, 6, 23, 7, 22, 8, 
                    21, 9, 20, 10, 19, 11, 18, 12, 17, 13, 16, 14, 15, 25}; 
 
/* 
 *  This program takes an unsorted array, sorts it using qsort, and then 
 *  calls bsearch for each element in the array, making sure that bsearch 
 *  returns the correct element. 
 */ 
 
main() 
{ 
    int i; 
    int failure = FALSE; 
    int *rkey; 
 
    qsort(array, SSIZE, sizeof(array[0]), &compare); 
 
    /* search for each element */ 
    for (i = 0; i < SSIZE - 1; i++) 
        { 
        /* search array element i */ 
        rkey = bsearch((array+i), array, SSIZE, sizeof(array[0]), &compare); 
        /* check for successful search */ 
        if (&array[i] != rkey) 
          { 
           printf("Not in array, array element %d\n", i); 
           failure = TRUE; 
           break; 
          } 
        } 
    if (!failure) 
        printf("All elements successfully found!\n"); 
} 
 
/* 
 *  Simple comparison routine. 
 * 
 *  Returns:  = 0 if a == b 
 *            < 0 if a < b 
 *            > 0 if a > b 
 */ 
int compare(int *a, int *b) 
{ 
    return (*a - *b); 
} 


btowc

Converts a one-byte multibyte character to a wide character in the initial shift state.

Format

#include <wchar.h>

wint_t btowc (int c);


ARGUMENTS

c

The character to be converted to a wide-character representation.

DESCRIPTION

This function determines whether ( unsigned char )c is a valid one-byte multibyte character in the initial shift state, and if so, returns a wide-character representation of that character.

Return Values

x The wide-character representation of unsigned char c .
WEOF Indicates an error. The c argument has the value EOF or does not constitute a valid one-byte multibyte character in the initial shift state.

bzero

Copies null characters into byte strings.

Format

#include <strings.h>

void bzero (void *string, size_t length);


ARGUMENTS

string

Specifies the byte string into which you want to copy null characters.

length

Specifies the length (in bytes) of the string.

DESCRIPTION

This function copies null characters ('\0') into the byte string pointed to by string for length bytes. If length is 0 (zero), then no bytes are copied.

cabs

Computes the Euclidean distance between two points as the square root of their respective squares, returning the following value:

sqrt(x2 + y2)


Format

#include <math.h>

double cabs (cabs_t z);


ARGUMENTS

z

A structure of type cabs_t . This type is defined in the <math.h> header file as follows:


Previous Next Contents Index