iconv(3C)
NAME
iconvsize, iconvopen, iconvclose, iconvlock, ICONV, ICONV1, ICONV2 − code set conversion routines
SYNOPSIS
#include <iconv.h>
int iconvsize(const char *tocode, const char *fromcode);
iconvd iconvopen(const char *tocode, const char *fromcode, unsigned char *table, int d1, int d2);
int iconvclose(iconvd cd);
int iconvlock(iconvd cd, int direction, int lock, const char *s);
int ICONV(iconvd cd, const unsigned char **inchar, size_t *inbytesleft, unsigned char **outchar, size_t *outbytesleft);
int ICONV1(iconvd cd, unsigned char *to, unsigned char *from, size_t buflen);
int ICONV2(iconvd cd, unsigned char *to, unsigned char *from, size_t buflen);
Remarks
For conformance to standards currently under development, the interfaces described in this manual entry may be replaced with others in a future release. To make migration easier, application writers should take care to isolate use of these functions.
DESCRIPTION
iconvsize() Find 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, −1 is returned. If a conversion table is not needed, 0 is returned.
iconvopen() Perform 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 return 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. iconvsize() can be used to determine whether 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. Currently supported multi-byte code sets can have character lengths of one or two bytes. If a one-byte character is unmapped, the default one-byte character d1 is used. Similarly, if a two-byte character is unmapped, 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, the result of this double conversion is the same as the original data.
iconvclose() Close 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 iconvlock(). If direction is 0, string s is used as a lock-shift sequence for the "converted from" or input data. If direction is 1, 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. iconvlock() also resets any state information to the initial shift state.
ICONV() Fetch a character in the "converted from" code set from an input buffer, convert the character to the "converted to" code set and place 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() Convert single-byte characters in from according to the conversion identified by cd and return the converted value in to. ICONV1() assumes from contains only single-byte characters.
ICONV2() Similarly convert double-byte characters in from according to the conversion identified by cd and return 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 bytes 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 −1 if a table is needed and it does not exist. The function returns 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 character 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()
ICONV2() Both return the number of bytes converted if successful. Otherwise they return −1.
EXAMPLES
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.
SEE ALSO
Hewlett-Packard Company — HP-UX Release 9.0: August 1992