ICONV(3C)

NAME

iconvsize, iconvopen, iconvclose, iconvlock, ICONV, ICONV1, ICONV2 − code set conversion routines

SYNOPSIS

#include <iconv.h>

int iconvsize (tocode, fromcode)
char *tocode;
char *fromcode;

iconvd iconvopen (tocode, fromcode, table, d1, d2)
char *tocode;
char *fromcode;
unsigned char *table;
int d1;
int d2;

int iconvclose (cd)
iconvd cd;

int iconvlock( cd, direction, lock, s)
iconvd cd;
int direction;
int lock;
char *s;

int ICONV (cd, inchar, inbytesleft, outchar, outbytesleft)
iconvd cd;
unsigned char **inchar;
int *inbytesleft;
unsigned char **outchar;
int *outbytesleft;

int ICONV1 (cd, to, from, buflen)
iconvd cd;
unsigned char *to;
unsigned char *from;
int buflen;

int ICONV2 (cd, to, from, buflen)
iconvd cd;
unsigned char *to;
unsigned char *from;
int buflen;

DESCRIPTION

Iconvsize finds the size of a table if one is needed to convert characters from the code set specified by the fromcode argument to the code set specified by the tocode argument. If a conversion table is needed and the table exists, the size of the table in bytes is returned. If a table is needed and the table does not exist, a -1 is returned. If a conversion table is not needed, a 0 is returned.

Iconvopen performs all initializations that have to be done to convert characters from the code set specified by the fromcode argument to the code set specified by the tocode argument and returns a conversion descriptor of type iconvd that identifies the conversion. Up to MAX_CD conversions can be open simultaneously. See iconv(1) for HP supplied fromcode and tocode names and their corresponding code sets. For conversions that require a table, the table argument is a pointer to the start of the conversion table. It is the caller’s responsibility to allocate sufficient memory for the table which is given by iconvsize. For conversions that do not require a table, the table argument must be a NULL pointer. The iconvsize function can be used to determine if a table is needed. For multi-byte code sets, a "converted from" character is mapped to a default character (d1 or d2) if it does not have an equivalent in the "converted to" code set. The multi-byte code sets currently supported can have character lengths of one or two bytes. If a one-byte character is unmapped, then the default one-byte character d1 is used. Similarly, if a two-byte character is unmapped, then the default two-byte character d2 is used. Default characters are used since different multi-byte code sets typically do not have the same number of characters which makes a one-to-one mapping difficult. Also unused sections in multi-byte code sets are usually reserved for future use. A different approach is taken with single-byte code sets. For single-byte code sets, it is assumed that the translation table forces a one-to-one mapping between the "from" and "to" characters. No default characters are used with single-byte code sets. This one-to-one mapping guarantees that the conversion is reversible. For example, if the output of a ROMAN8 to ISO 8859/1 conversion is converted back to ROMAN8, then the result of this double conversion is the same as the original data.

Iconvclose closes the conversion descriptor cd freeing it up for a subsequent iconvopen. It is the caller’s responsibility to de-allocate any table associated with the cd conversion descriptor.

If needed, code set lock-shift information for the conversion identified by cd can be initialized by the iconvlock function. If direction is 0, then string s is used as a lock-shift sequence for the "converted from" or input data. If direction is 1, then string s is used as a lock-shift sequence for the "converted to" or output data. Currently, three lock-shift sequences can be used in a conversion: lock-shift 0, lock-shift 1 and lock-shift 2. These are identified by the lock parameter values 0, 1 and 2. The iconvlock function also resets any state information to the initial shift state.

ICONV fetches a character in the "converted from" code set from an input buffer, converts the character to the "converted to" code set and places it plus any lock-shift information into an output buffer. The descriptor cd identifies the conversion. The contents of inchar points to a single- or multi-byte character in the input buffer and inbytesleft points to the number of bytes from the input character to the end of the buffer. The contents of outchar points to the next available space in the output buffer and outbytesleft points to the number of the bytes from the next available space to the end of the buffer. While conversions are done from the input buffer to the output buffer, the contents of inchar, inbytesleft, outchar and outbytesleft are incremented or decremented to reflect the current status of the input and output buffers.

ICONV1 and ICONV2 are used where it is more efficient to handle single- and multi-byte characters separately. These routines do not check for lock-shift information. ICONV1 converts single-byte characters in from according to the conversion identified by cd and returns the converted value in to. ICONV1 assumes from contains only single-byte characters. Similarly, ICONV2 converts double-byte characters in from according to the conversion identified by cd and returns the converted value in to. ICONV2 assumes from contains only double-byte characters. The buflen argument in both ICONV1 and ICONV2 specifies the number of byes that will be converted.

EXTERNAL INFLUENCES

International Code Set Support

Single- and multi-byte character code sets are supported.

RETURN VALUES

Iconvsize returns the size of the conversion table in bytes if a table is needed and it exists. The function returns a -1 if a table is needed and it does not exist. The function returns a 0 if a table is not needed.

Iconvopen returns a conversion descriptor if successful; otherwise a (iconvd) -1 is returned.

Iconvclose returns a non-negative number if successful; otherwise a -1 is returned.

ICONV returns 0 if all characters from the input buffer are successfully converted and placed into the output buffer. ICONV returns 1 if a multi-byte input character or a lock-shift sequence spans the input buffer boundary. No conversion is attempted on the character and the contents of inchar points to the start of the truncated character sequence. ICONV returns 2 if an input character does not belong to the "converted from" character set. No conversion is attempted on the character and the contents of inchar points to the start of the unidentified input character. ICONV returns 3 if there is no room in the output buffer to place the converted character. The converted characters is not placed in the output buffer and the contents of inchar points to the start of the character sequence that caused the output buffer overflow.

ICONV1 and ICONV2 return the number of bytes converted if successful; otherwise a -1 is returned.

EXAMPLE

int
convert( tocode, fromcode, d1, d2)
char *tocode;/* tocode name */
char *fromcode;/* fromcode name */
int d1;/* one-byte default character */
int d2;/* two-byte default character */
{
extern void error();/* local error message */
iconvd cd;/* conversion descriptor */
int size;/* size of translation table */
unsigned char *table;/* ptr to translation table */
int bytesread;/* num bytes read into input buffer */
unsigned char inbuf[BUFSIZ];/* input buffer */
unsigned char *inchar;/* ptr to input character */
int inbytesleft;/* num bytes left in input buffer */
unsigned char outbuf[BUFSIZ];/* output buffer */
unsigned char *outchar;/* ptr to output character */
int outbytesleft;/* num bytes left in output buffer */
/* create conversion table */
if ((size = iconvsize( tocode, fromcode)) == BAD) {
error( FATAL, BAD_SIZE);
}
else if (size == 0) {
table = (unsigned char *) NULL;
}
else if ((table = (unsigned char *) malloc ( (unsigned int) size)) == (unsigned char *) NULL) {
error( FATAL, BAD_CREATE);
}
/* start up a conversion */
if ((cd = iconvopen( tocode, fromcode, table, d1, d2)) == (iconvd) BAD) {
error( FATAL, BAD_OPEN);
}
inchar = inbuf;
inbytesleft = 0;
outchar = outbuf;
outbytesleft = BUFSIZ;
/* translate the characters */
for ( ;; ) {
switch (ICONV( cd, &inchar, &inbytesleft, &outchar, &outbytesleft)) {
case 0:
case 1:
/*
** Done with buffer, empty buffer or character spans
** input buffer boundary. Move any remaining stuff
** to start of buffer, get more characters and
** reinitialize input variables. If at EOF, flush
** output buffer and leave; otherwise, continue to
** convert the characters.
*/
strncpy( inbuf, inchar, inbytesleft);
if ((bytesread = read( Input, inbuf+inbytesleft, BUFSIZ-inbytesleft)) < 0) {
perror( "prog");
return BAD;
}
if (! (inbytesleft += bytesread)) {
if (write( 1, outbuf, BUFSIZ - outbytesleft) < 0) {
perror( "prog");
return BAD;
}
goto END_CONVERSION;
}
inchar = inbuf;
break;
case 2:
error( FATAL, BAD_CONVERSION);
case 3:
/*
** Full buffer or output character spans output buffer
** boundary. Send the output buffer to stdout,
** reinitialize the output variables.
*/
if (write( 1, outbuf, BUFSIZ - outbytesleft) < 0) {
perror( "prog");
return BAD;
}
outchar = outbuf;
outbytesleft = BUFSIZ;
}
}
END_CONVERSION:
/* end conversion & get rid of the conversion table */
if (iconvclose( cd) == BAD) {
error( FATAL, BAD_CLOSE);
}
if (size) {
free( (char *) table);
}
return GOOD;
}

AUTHOR

Iconv was developed by HP.

Museum

Related Articles