Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

geniconvtbl(1)

Name

geniconvtbl - generate code conversion tables

Synopsis

geniconvtbl [-fnq] [-p preprocessor] [-W arg] [-Dname] 
     [-Dname=def] [-Idirectory] [-Uname] [infile]...
geniconvtbl [-fnq] -c -F [infile]...
geniconvtbl [-fnq] -c -T [infile]...

Description

The geniconvtbl utility accepts code conversion rules defined in flat text file(s) and writes code conversion binary table file(s) that can be used to support user-defined iconv code conversion, cconv code conversion, or both (see iconv(1), iconv(3C), and cconv(3C) for more detail on the iconv code conversions).

The input and output files can be of two different formats:

When the –c option is provided, the geniconvtbl will accept one or more of infile or standard input stream in the format described in geniconvtbl-cconv(5) and will generate cconv binary table file(s) for cconv and iconv code conversions.

Unlike the iconv binary tables which is basically for buffer-based iconv code conversions only, the cconv binary tables are per-character sequence based and for both iconv and cconv code conversions.

Options

The following options are supported:

–c

Generates cconv code conversion table.

–f

Overwrites output file if the output file exists.

–F

Together with the –c option, indicates that the conversion direction is from UTF-32 to a codeset. Without the –c option, this option is ignored with a warning message.

–n

Does not generate an output file. This is useful to check the contents of the input file.

–p preprocessor

Uses specified preprocessor instead of the default preprocessor, /usr/lib/cpp.

–q

Quiet option. It suppresses warning and error messages.

–T

Together with the –c option, indicates that the conversion direction is from a codeset to UTF-32. Without the –c option, this option is ignored with a warning message.

–W arg

Passes the argument arg to the preprocessor. If this option is specified more than once, all arguments are passed to the preprocessor.

–Dname
–Dname=def
–Idirectory
–Uname

geniconvtbl recognizes these options and passes them and their arguments to the preprocessor.

Operands

The following operand is supported:

infile

A path name of an input file. If no input file is specified, geniconvtbl reads from the standard input stream. The user can specify more than one input file if necessary.

OUTPUT

If input is from the standard input stream, geniconvtbl writes output to the standard output stream. If one or more input files are specified, geniconvtbl reads from each input file and writes to a corresponding output file. Each of the output file names will be the same as the corresponding input file with either .bt appended or the suffix starting with . character replaced with .bt.

In order to use the iconv binary table files generated without using the –c option as code conversion modules for iconv(1) and iconv(3C), they must be moved to the following directory:

/usr/lib/iconv/geniconvtbl/binarytables/

The file names in that directory must start with one or more printable ASCII characters as the fromcode name followed by a percentage character (%), followed by one or more printable ASCII characters as the tocode name, followed by the suffix .bt. The fromcode and tocode names are used to identify the iconv code conversion at iconv(1) and iconv_open(3C).

In order to use the cconv binary table files generated by using the –c option, they must be moved to the following directory:

/usr/lib/iconv/

The cconv binary table files should come in a pair, providing a conversion from UTF-32 to a codeset generated by using '–c –F' options with the following naming convention:

UTF-32+<codeset>.bt

and the other conversion from a codeset to UTF-32 generated by using '–c –T' options with the following naming convention:

<codeset>+UTF-32.bt

where the <codeset> should be one or more of printable ASCII characters denoting the codeset name.

Examples

Example 1 Generating an iconv code conversion binary table

The following example generates a code conversion binary table with output file name convertA2B.bt:

example% geniconvtbl convertA2B
Example 2 Generating multiple iconv code conversion binary tables

The following example generates two code conversion binary tables with output files test1.bt and test2.bt:

example% geniconvtbl test1 test2
Example 3 Using another preprocessor

The following example generates a code conversion binary table once the specified preprocessor has processed the input file:

example% geniconvtbl -p /opt/SUNWspro/bin/cc -W -E convertB2A
Example 4 Placing a binary table for iconv

To use the binary table created in the first example above as the engine of the conversion 'fromcode' ABC to 'tocode' DEF, become super-user and then rename it and place it like this:

example# mv convertA2B.bt \
    /usr/lib/iconv/geniconvtbl/binarytables/ABC%DEF.bt
Example 5 Providing modified ISO8859-1 to UTF-8 code conversion

Write a geniconvtbl source file that defines the code conversion. For instance, you can copy over /usr/lib/iconv/geniconvtbl/srcs/ISO8859-1_to_UTF-8.src into your directory and make necessary changes at the source file. Once the modifications are done, generate the binary table:

example% geniconvtbl ISO8859-1_to_UTF-8.src

As super-user, place the generated binary table with a unique name at the system directory where iconv_open(3C) can find the binary table:

example su
Password:
example% cp ISO8859-1_to_UTF-8.bt \
    /usr/lib/iconv/geniconvtbl/binarytables/my-iso-8859-1%utf-8.bt

After that, you can do the iconv code conversion. For instance:

example% iconv -f my-iso-8859-1 -t utf-8 testfile.txt
Example 6 Generating cconv code conversion binary tables

The following example generates code conversion binary table with output file name UTF-32+my8859-11.bt:

example% geniconvtbl -c -F UTF-32+my8859-11.TXT

The following example generates code conversion binary table with output file name my8859-11+UTF-32.bt:

example% geniconvtbl -c -T my8859-11+UTF-32.TXT
Example 7 Placing the binary tables for cconv

To use the cconv binary tables created in the Example 6 for cconv and iconv code conversions, become super-user and then place the files under /usr/lib/iconv:

example# mv my8859-11+UTF-32.bt UTF-32+my8859-11.bt \
           /usr/lib/iconv/

After that, you can do iconv and cconv code conversions not only between UTF-32 and my8859-11, but also between my8859-11 and any other codeset names that have corresponding cconv binary table files installed in the system.

Environment Variables

See environ(7) for descriptions of the following environment variables that affect the execution of geniconvtbl: LANG and LC_CTYPE.

Exit Status

The following exit values are returned:

0

No errors occurred and the output files were successfully created.

1

Command line options are not correctly used or an unknown command line option was specified.

2

Invalid input or output file was specified.

3

Conversion rules in input files are not correctly defined.

4

Conversion rule limit of input files has been reached. See NOTES section of geniconvtbl(5).

5

No more system resource error.

6

Internal error.

Files

/usr/lib/iconv/*.bt

cconv code conversion binary table files for iconv(1), cconv(3C), and iconv(3C)

/usr/lib/iconv/geniconvtbl/binarytables/*.bt

iconv code conversion binary table files for iconv(1) and iconv(3C)

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os

See Also

cpp(1), iconv(1), localedef(1), cconv(3C), cconv_close(3C), cconv_open(3C), cconvctl(3C), iconv(3C), iconv_close(3C), iconv_open(3C), iconvctl(3C). geniconvtbl(5), geniconvtbl-cconv(5), attributes(7), environ(7)

International Language Environments Guide for Developers

Notes

The generated and correctly placed output files, /usr/lib/iconv/*.bt and /usr/lib/iconv/geniconvtbl/binarytables/*.bt, are used in both 32-bit and 64-bit environments.

If you overwrite files in the /usr/lib/iconv directory that were delivered as a part of the Solaris installation, your modules will be overwritten during a system update.