United States    
COMPAQ STORE | PRODUCTS |
SERVICES | SUPPORT | CONTACT US | SEARCH
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


iconv

Converts characters coded in one codeset to characters coded in another codeset.

Format

#include <iconv.h>

size_t iconv (iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);


Arguments

cd

A conversion descriptor. This is returned by a successful call to iconv_open .

inbuf

A pointer to a variable that points to the first character in the input buffer.

inbytesleft

Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the input buffer (inbuf). When the conversion is completed, the variable indicates the number of bytes in inbuf not converted.

outbuf

A pointer to a variable that points to the first available byte in the output buffer. The output buffer contains the converted characters.

outbytesleft

Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the output buffer (outbuf). When the conversion is completed, the variable indicates the number of bytes left in outbuf.

Description

This function converts characters in the buffer pointed to by inbuf to characters in another code set. The resulting characters are stored in the buffer pointed to by outbuf. The conversion type is specified by the conversion descriptor cd. This descriptor is returned from a successful call to iconv_open .

If an invalid character is found in the input buffer, the conversion stops after the last successful conversion. The variable pointed to by inbytesleft is updated to reflect the number of bytes in the input buffer that are not converted. The variable pointed to by outbytesleft is updated to reflect the number of bytes remaining in the output buffer.


Return Values

x Number of non-identical conversions performed. Indicates successful conversion. In most cases 0 is returned.
( size_t ) --1 Indicates an error condition. The function sets errno to one of the following:
  • EBADF -- The cd argument is not a valid conversion descriptor.
  • EILSEQ -- The conversion stops when an invalid character detected.
  • E2BIG -- The conversion stops because of insufficient space in the output buffer.
  • EINVAL -- The conversion stops because of an incomplete character at the end of the input buffer.

iconv_close

Deallocates a specified conversion descriptor and the resources allocated to the descriptor.

Format

#include <iconv.h>

int iconv_close (iconv_t cd);


Arguments

cd

The conversion descriptor to be deallocated. A conversion descriptor is returned by a successful call to iconv_open .

Return Values

0 Indicates that the conversion descriptor was successfully deallocated.
--1 Indicates an error occurred. The function sets errno to one of the following:
  • EBADF -- The cd argument is not a valid conversion descriptor.
  • EVMSERR -- Non-translatable VMS error occur. vaxc$errno contains the VMS error code.

iconv_open

Allocates a conversion descriptor for a specified codeset conversion.

Format

#include <iconv.h>

iconv_t iconv_open (const char *tocode, const char *fromcode);


Arguments

tocode

The name of the codeset to which characters are converted.

fromcode

The name of the source codeset. See Chapter 10 for information on obtaining a list of currently available codesets or for details on adding new codesets.

Return Values

x A conversion descriptor. Indicates the call was successful. This descriptor is used in subsequent calls to iconv
(iconv_t) --1 Indicates an error occurred. The function sets errno to one of the following:
  • EMFILE -- The process does not have enough I/O channels to open a file.
  • ENOMEM -- Insufficient space is available.
  • EINVAL -- The conversion specified by fromcode and tocode is not supported.
  • EVMSERR -- Nontranslatable VMS error occur. vaxc$errno contains the VMS error code. A value of SS$_BADCHKSUM in vaxc$errno indicates that a conversion table file was found, but its contents is corrupted. A value of SS$_IDMISMATCH in vaxc$errno indicates that the conversion table file version does not match the version of the C Run-Time Library.

Example


#include <stdio.h> 
#include <iconv.h> 
#include <errno.h> 
 
 
int main() 
{ 
    /* Declare variables to be used                      */ 
 
    char fromcodeset[30]; 
    char tocodeset[30]; 
    int iconv_opened; 
    iconv_t iconv_struct;       /* Iconv descriptor      */ 
 
    /* Initialize variables                              */ 
 
    sprintf(fromcodeset, "DECHANYU"); 
    sprintf(tocodeset, "EUCTW"); 
    iconv_opened = FALSE; 
 
    /* Attempt to create a conversion descriptor for the */ 
    /* codesets specified. If the return value from      */ 
    /* iconv_open is -1 then an error has occurred.      */ 
    /*  Check the value of errno.                        */ 
 
    if ((iconv_struct = iconv_open(tocodeset, fromcodeset)) 
       == (iconv_t) - 1) { 
 
        /* Check the value of errno                      */ 
 
        switch (errno) { 
        case EMFILE: 
        case ENFILE: 
            printf("Too many iconv conversion files open\n"); 
            break; 
 
        case ENOMEM: 
            printf("Not enough memory\n"); 
            break; 
 
        case EINVAL: 
            printf("Unsupported conversion\n"); 
            break; 
 
        default: 
            printf("Unexpected error from iconv_open\n"); 
            break; 
       } 
    } 
    else 
 
        /* Successfully allocated a conversion descriptor   */ 
 
        iconv_opened = TRUE; 
 
    /*  Was a conversion descriptor allocated               */ 
 
    if (iconv_opened) { 
 
        /* Attempt to deallocate the conversion descriptor. */ 
        /* If iconv_close returns -1 then an error has      */ 
        /* occurred.                                        */ 
 
        if (iconv_close(iconv_struct) == -1) { 
 
            /* An error occurred. Check the value of errno  */ 
 
            switch (errno) { 
            case EBADF: 
                printf("Conversion descriptor is invalid\n"); 
                break; 
            default: 
                printf("Unexpected error from iconv_close\n"); 
                break; 
            } 
        } 
    } 
    return (EXIT_FAILURE); 
} 


[w]inch

Return the character at the current cursor position on the specified window without making changes to the window. The inch function acts on the stdscr window.

Format

#include <curses.h>

char inch();

char winch (WINDOW *win);


Argument

win

A pointer to the window.

Return Values

x The returned character.
ERR Indicates an input error.

index

Search for a character in a string.

Format

#include <strings.h>

char *index (const char *s, int c);

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

s

The string to search.

c

The character to search for.

Description

The index function is identical to the strchr function, and is provided for compatibility with some UNIX implementations.

initscr

Initializes the terminal-type data and all screen functions. You must call initscr before using any of the curses functions.

Format

#include <curses.h>

void initscr (void);


Description

The OpenVMS Curses version of this function clears the screen before doing the initialization. The BSD-based Curses version does not.

initstate

Initializes random number generators.

Format

#include <stdlib.h>

char *initstate (unsigned int seed, char *state, int size);


Arguments

seed

An initial seed value.

state

Pointer to an array of state information.

size

The size of the state information array.

Description

This function initializes random number generators. It lets you initialize for future use, a state array passed as an argument. The size in bytes of the state array is used by the initstate function to decide how sophisticated a random number generator to use; the larger the state array, the more random the numbers.

Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. Amounts less than 8 bytes generate an error, while other amounts are rounded down to the nearest known value.

The seed argument specifies a starting point for the random number sequence and provides for restarting at the same point. The initstate function returns a pointer to the previous state information array.

Once you initialize a state, the setstate function allows rapid switching between states. The array defined by the state argument is used for further random number generation until the initstate function is called or the setstate function is called again. The setstate function returns a pointer to the previous state array.

After initialization, you can restart a state array at a different point in one of two ways:

See also setstate , and srandom , in this section.


Return Values

x A pointer to the previous state array information.
0 Indicates an error. Call made with less than 8 bytes of state information. Further specified in the global errno .

[w]insch

Insert a character at the current cursor position in the specified window. The insch function acts on the stdscr window.

Format

#include <curses.h>

int insch (char ch);

int winsch (WINDOW *win, char ch);


Arguments

win

A pointer to the window.

ch

The character to be inserted.

Description

After the character is inserted, each character on the line shifts to the right, and the last character in the line is deleted. For more information, see the scrollok function in this section.

Return Values

OK Indicates success.
ERR Indicates that the function makes the screen scroll illegally.

[w]insertln

Insert a line above the line containing the current cursor position. The insertln function acts on the stdscr window.

Format

#include <curses.h>

int insertln();

int winsertln (WINDOW *win);


Argument

win

A pointer to the window.

Description

The current line and every line below it shifts down, and the bottom line disappears. The inserted line is blank and the current (y,x) coordinates remain the same. For more information, see the scrollok function in this section.

Return Values

OK Indicates success.
ERR Indicates that the function makes the screen scroll illegally.

[w]insstr

Insert a string at the current cursor position in the specified window. The insstr function acts on the stdscr window.

Format

#include <curses.h>

int insstr (char *str);

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


Arguments

win

A pointer to the window.

str

A pointer to the string to be inserted.

Description

Each character after the string shifts to the right, and the last character disappears. These functions are specific to Compaq C for OpenVMS Systems and are not portable.

Return Values

OK Indicates success.
ERR Indicates that the function makes the screen scroll illegally. For more information, see the scrollok function in this section.

isalnum

Indicates if a character is classed either as alphabetic or as a digit in the program's current locale.

Format

#include <ctype.h>

int isalnum (int character);


Argument

character

An object of type int . The value of character must be representable as an unsigned char or must equal the value of the macro EOF. If it has any other value, the behavior is undefined.

Return Values

nonzero If alphanumeric.
0 If not alphanumeric.

isalpha

Indicates if a character is classed as an alphabetic character in the program's current locale.

Format

#include <ctype.h>

int isalpha (int character);


Argument

character

An object of type int . The value of character must be representable as an unsigned char or must equal the value of the macro EOF. If it has any other value, the behavior is undefined.

Return Values

nonzero If alphabetic.
0 If not alphabetic.

isapipe

Indicates if a specified file descriptor is associated with a pipe.

Format

#include <unixio.h>

int isapipe (int file_desc);


Argument

file_desc

A file descriptor.

Description

For more information about pipes, see Chapter 5.

Return Values

1 Indicates an association with a pipe.
0 Indicates no association with a pipe.
--1 Indicates an error (for example, if the file descriptor is not associated with an open file).

isascii

Indicates if a character is an ASCII character.

Format

#include <ctype.h>

int isascii (int character);


Argument

character

An object of type char .

Return Values

nonzero If ASCII.
0 If not ASCII.

isatty

Indicates if a specified file descriptor is associated with a terminal.

Format

#include <unistd.h>

int isatty (int file_desc);


Argument

file_desc

A file descriptor.

Return Values

1 If the file descriptor is associated with a terminal.
0 If the file descriptor is not associated with a terminal.
--1 Indicates an error (for example, if the file descriptor is not associated with an open file).

iscntrl

Indicates if a character is classed as a control character in the program's current locale.

Format

#include <ctype.h>

int iscntrl (int character);


Argument

character

An object of type int . The value of character must be representable as an unsigned char or must equal the value of the macro EOF. If it has any other value, the behavior is undefined.

Return Values

nonzero If a control character.
zero If not a control character.

isdigit

Indicates if a character is classed as a digit in the program's current locale.

Format

#include <ctype.h>

int isdigit (int character);


Argument

character

An object of type int . The value of character must be representable as an unsigned char or must equal the value of the macro EOF. If it has any other value, the behavior is undefined.

Return Values

nonzero If a decimal digit.
0 If not a decimal digit.

isgraph

Indicates if a character is classed as a graphic character in the program's current locale.

Format

#include <ctype.h>

int isgraph (int character);


Argument

character

An object of type int . The value of character must be representable as an unsigned char or must equal the value of the macro EOF. If it has any other value, the behavior is undefined.

Return Values

nonzero If a graphic character.
0 If not a graphic character.


Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement