United States    
COMPAQ
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

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 Compaq 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();  /* 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); 
}

This example program outputs the following: 


All elements successfully found!

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: 


typedef struct {double x,y;} cabs_t;

Description

On overflow, the return value is undefined.

calloc

Allocates an area of zeroed memory. This function is AST-reentrant.

Format

#include <stdlib.h>

void *calloc (size_t number, size_t size);

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

number

The number of items to be allocated.

size

The size of each item.

Description

The calloc function initializes the items to 0.

See also malloc and realloc in this section.

Return Values

n The address of the first byte, which is aligned on a quadword boundary.
NULL Indicates an inability to allocate the space.

catclose

Closes a message catalog.

Format

#include <nl_types.h>

int catclose (nl_catd catd);

Arguments

catd

A message catalog descriptor. This is returned by a successful call to catopen.

Description

This function closes the message catalog referenced by catd and frees the catalog file descriptor.

Return Values

0 Indicates that the catalog was successfully closed.
--1 Indicates that an error occurred. The function sets errno to the following value:
  • EBADF -- The catalog descriptor is not valid.

catgets

Retrieves a message from a message catalog.

Format

#include <nl_types.h>

char *catgets (nl_catd catd, int set_id, int msg_id, const char *s);

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

catd

A message catalog descriptor. This is returned by a successful call to catopen.

set_id

An integer set identifier.

msg_id

An integer message identifier.

s

A pointer to a default message string that is returned by the function if the message cannot be retrieved.

Description

This function retrieves a message identified by set_id and msg_id, in the message catalog catd. The message is stored in a message buffer in the nl_catd structure, which is overwritten by subsequent calls to catgets. If a message string needs to be preserved, it should be copied to another location by the program.

Return Values

x Pointer to the retrieved message.
s Pointer to the default message string. Indicates that the function is not able to retrieve the requested message from the catalogue. This condition can arise if the requested pair ( set_d, msg_id) does not represent an existing message from the open catalogue, or it indicates that an error occurred. If an error occurred, the function sets errno to one of the following values:
  • EBADF -- The catalog descriptor is not valid.
  • EVMSRR -- A VMS I/O read error; the VMS error code can be found in vaxc$errno .

Example


#include <nl_types.h> 
#include <locale.h> 
#include <stdarg.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <unixio.h> 
 
/* This test makes use of all the message catalog routines. catopen()    */ 
/* opens the catalog ready for reading, then each of the three messages  */ 
/* in the catalog are extracted in turn using catgets() and printed out. */ 
/* catclose() closes the catalog after use.                              */ 
/* The catalog source file used to create the catalog is as follows:     */ 
/* $ this is a message file 
 * $ 
 * $quote " 
 * $ another comment line 
 * $set 1 
 * 1 "First set, first message" 
 * 2 "second message -- This long message uses a backslash \
 * for continuation." 
 * $set 2 
 * 1 "Second set, first message"                                         */ 
 
char *default_msg = "this is the first message."; 
 
main() 
{ 
    nl_catd catalog; 
    int msg1, 
        msg2, 
        retval; 
 
    char *cat = "sys$disk:[]catgets_example.cat"; /* Force local catalog */ 
 
    char *msgtxt; 
 
    char string[128]; 
 
    /* Create the message test catalog */ 
 
    system("gencat catgets_example.msgx catgets_example.cat") ; 
 
    if ((catalog = catopen(cat, 0)) == (nl_catd) - 1) { 
        perror("catopen"); 
        exit(EXIT_FAILURE); 
    } 
 
    msgtxt = catgets(catalog, 1, 1, default_msg); 
    printf("%s\n", msgtxt); 
 
    msgtxt = catgets(catalog, 1, 2, default_msg); 
    printf("%s\n", msgtxt); 
 
    msgtxt = catgets(catalog, 2, 1, default_msg); 
    printf("%s\n", msgtxt); 
 
    if ((retval = catclose(catalog)) == -1) { 
        perror("catclose"); 
        exit(EXIT_FAILURE); 
    } 
 
    delete("catgets_example.cat;") ;  /* Remove the test catalog */ 
}

Running the example program produces the following result: 


First set, first message 
second message -- This long message uses a backslash for continuation. 
Second set, first message

catopen

Opens a message catalog.

Format

#include <nl_types.h>

nl_catd catopen (const char *name, int oflag);

Arguments

name

The name of the message catalog to open.

oflag

An object of type int that determines whether the locale set for the LC_MESSAGES category in the current program's locale or the logical name LANG is used to search for the catalog file.

Description

This function opens the message catalog identified by name.

If name contains a colon (:), a square opening bracket ([), or an angle bracket (<), or is defined as a logical name, then it is assumed that name is the complete file specification of the catalog.

If it does not include these characters, catopen assumes that name is a logical name pointing to an existing catalog file. If name is not a logical name, then the logical name NLSPATH is used to define the file specification of the message catalog. NLSPATH is defined in the user's process. If the NLSPATH logical name is not defined, or no message catalog can be opened in any of the components specified by the NLSPATH, then the SYS$NLSPATH logical name is used to search for a message catalog file.

Both NLSPATH and SYS$NLSPATH is a comma-separated list of templates. The catopen function uses each template to construct a file specification. For example, NLSPATH could be defined as: 


DEFINE NLSPATH SYS$SYSROOT:[SYS$I18N.MSG]%N.CAT,SYS$COMMON:[SYSMSG]%N.CAT

In this example, catopen first searches the directory SYS$SYSROOT:[SYS$I18N.MSG] for the named catalog. If the named catalog is not found there, the directory SYS$COMMON:[SYSMSG] is searced. The catalog name is constructed by substituting %N with the name passed to catopen , and adding the .cat suffix. %N is known as a substitution field. The following substitution fields are valid:
Field Meaning
%N Substitute the name passed to catopen
%L 1 Substitute the locale name.

The period (.) and at-sign (@) characters in the locale name are replaced by an underscore (_) character.

For example, the "zh_CN.dechanzi@radical" locale name results in a substitution of ZH_CN_DECHANZI_RADICAL.

%l 1 Substitute the language part of the locale name. For example, the language part of the en_GB.ISO8859-1 locale name is en.
%t 1 Substitute the territory part of the locale name. For example, the territory part of the en_GB.ISO8859-1 locale is GB.
%c 1 Substitute the codeset name from the locale name. For example, the codeset name of the en_GB.ISO8859-1 locale name is ISO8859-1.

1This substitution assumes that the locale name is of the form language_territory.codeset@mode

If the oflag argument is set to NL_CAT_LOCALE, then the current locale as defined for the LC_MESSAGES category is used to determine the substitution for the %L, %l, %t, and %c substitution fields. If the oflag argument is set to 0, then the value of the LANG environment variable is used as a locale name to determine the substitution for these fields. Note that using NL_CAT_LOCALE conforms to the XPG4 specification while a value of 0 (zero) exists for the purpose of preserving XPG3 compatibility. Note also, that catopen uses the value of the LANG environment variable without checking whether the program's locale can be set using this value. That is, catopen does not check whether this value can serve as a valid locale argument in the setlocale call.

If the substitution value is not defined, an empty string is substituted.

A leading comma or two adjacent commas (,,) is equivalent to specifying %N. For example, 


DEFINE NLSPATH ",%N.CAT,SYS$COMMON:[SYSMSG.%L]%N.CAT"

In this example, catopen searches in the following locations in the order shown:

  1. name (in the current directory)
  2. name.cat (in the current directory)
  3. SYS$COMMON:[SYSMSG.locale_name]name.cat

Return Values

x A message catalog file descriptor. Indicates the call was successful. This descriptor is used in calls to catgets and catclose .
(nl_catd) --1 Indicates an error occurred. The function sets errno to one of the following values:
  • EACCES -- Insufficient privilege or file protection violation, or file currently locked by another user.
  • EMFILE -- Process channel count exceeded.
  • ENAMETOOLONG -- The full file specification for message catalogue is too long
  • ENOENT -- Unable to find the requested message catalogue.
  • ENOMEM -- Insufficient memory available.
  • ENOTDIR -- Part of the name argument is not a valid directory.
  • EVMSERR -- An error occurred that does not match any errno value. Check the value of vaxc$errno .

Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement