International Language Environments Guide

Internationalization APIs in libc

The current Oracle Solaris environment offers two sets of APIs:

Wide-character codes are fixed-width units of logical entities. Therefore, you do not have to keep track of maintaining proper character boundaries when you are using multibyte characters.

When a program takes input from a file, you can convert your file's multibyte data into wide-character process code directly with input functions like fscanf and fwscanf or by using conversion functions like mbtowc and mbsrtowcs after the input. To convert output data from wide-character format to multibyte character format, use output functions like fwprintf and fprintf or apply conversion functions like wctomb and wcsrtombs before the output.

The tables in the remainder of this chapter describe the internationalization APIs included in the current Oracle Solaris system.

The following table describes the messaging function APIs in libc.

Table 2–1 Messaging Functions in libcp

Library Routine 

Description 

bindtextdomain()

Bind the path for a message domain 

catclose()

Close a message catalog 

catgets()

Read a program message 

catopen()

Open a message catalog 

dcgettext()

Get a message from a message catalog with domain and category specified 

dgettext()

Get a message from a message catalog with domain specified 

gettext()

Retrieve a text string from the message database 

textdomain()

Set and query the current domain 

The following table describes the code conversion function APIs in libc.

Table 2–2 Code Conversion in libc

Library Routine 

Description 

iconv()

Convert codes 

iconv_close()

Deallocate the conversion descriptor 

iconv_open()

Allocate the conversion descriptor 

The following table describes the regular expression APIs in libc.

Table 2–3 Regular Expressions in libc

Library Routine 

Description 

fnmatch()

Match file name or path name 

regcomp()

Compile the regular expression 

regerror()

Provide a mapping from error codes to error messages 

regexec()

Execute regular expression matching 

regfree()

Free memory allocated by regcomp()

The following table describes the wide character function APIs in libc.

Table 2–4 Wide Character Class in libc

Library Routine 

Description 

wctrans()

Define character mapping 

wctype()

Define character class 

The following table lists the modify and query locale in libc.

Table 2–5 Modify and Query Locale in libc

Library Routine 

Description 

setlocale()

Modify and query a program's locale 

The following table lists the query locale data in libc.

Table 2–6 Query Locale Data in libc

Library Routine 

Description 

localeconv()

Get monetary and numeric formatting information of current locale 

nl_langinfo()

Get language and cultural information of current locale 

The following table describes the character classification function APIs in libc.

Table 2–7 Character Classification and Transliteration in libc

Library Routine 

Description 

isalnum()

Is character alphabetic or digital? 

isalpha()

Is character alphabetic? 

isascii()

Is character an ASCII character? 

iscntrl()

Is character a control character? 

isdigit()

Is character a digit? 

isenglish()

Is wide character in English alphabet from a supplementary code set? 

isgraph()

Is character a visible character? 

isideogram()

Is wide character an ideogram? 

islower()

Is character lowercase? 

isnumber()

Is wide character a digit from a supplementary code set? 

isphonogram()

Is wide character a phonogram? 

isprint()

Is character printable? 

ispunct()

Is character a punctuation mark? 

isspace()

Is character a space? 

isspecial()

Is special wide character from a supplementary code set? 

isupper()

Is character uppercase? 

iswalnum()

Is wide character an alphabetic character or digit? 

iswalpha()

Is wide character alphabetic? 

iswascii()

Is wide character an ASCII character? 

iswcntrl()

Is wide character a control character? 

iswdigit()

Is wide-character a digit? 

iswgraph()

Is wide character a visible character? 

iswlower()

Is wide character lowercase? 

iswprint()

Is wide character a printable character? 

iswpunct()

Is wide character a punctuation mark? 

iswspace()

Is wide character a white space? 

iswupper()

Is wide character uppercase? 

iswxdigit()

Is wide character a hex digit? 

isxdigit()

Is character a hex digit? 

tolower()

Convert an uppercase character to lowercase. 

toupper()

Convert a lowercase character to uppercase. 

towctrans()

Wide character mapping. 

towlower()

Convert an uppercase wide character to lowercase. 

towupper()

Convert a lowercase wide character to uppercase. 

The following table describes the character collation function APIs in libc.

Table 2–8 Character Collation in libc

Library Routine 

Description 

strcoll()

Collate character strings 

strxfrm()

Transform character strings for comparison 

wcscoll()

Collate wide-character strings 

wcsxfrm()

Transform wide-character strings for comparison 

The following table describes the monetary handling function APIs in libc.

Table 2–9 Monetary Formatting in libc

Library Routine 

Description 

localeconv()

Get monetary formatting information for the current locale 

strfmon()

Convert monetary value to string representation 

The following table describes the date and time formatting in libc.

Table 2–10 Date and Time Formatting in libc

Library Routine 

Description 

getdate()

Convert user format date and time. 

strftime()

Convert date and time to string representation. The %u conversion function conforms to the X/Open CAE Specification, System Interfaces and Headers, Issue 4, Version 2. This function represents a weekday as a decimal number [1,7], with 1 now representing Monday.

strptime()

Date and time conversion. 

The following table describes the multibyte handling function APIs in libc.

Table 2–11 Multibyte Handling in libc

Library Routine 

Description 

btowc()

Single-byte to wide-character conversion 

mblen()

Get number of bytes in a character 

mbrlen()

Get number of bytes in character (restartable) 

mbrtowc()

Convert a character to a wide-character code (restartable) 

mbsinit()

Determine conversion object status 

mbsrtowcs()

Convert a character string to a wide-character string (restartable) 

mbstowcs()

Convert a character string to a wide-character string 

mbtowc()

Convert a character to a wide-character code 

The following table describes the wide character and string handling in libc.

Table 2–12 Wide Character and String Handling in libc

Library Routine 

Description 

wcrtomb()

Convert a wide-character code to a character (restartable) 

wcscat()

Concatenate wide-character strings 

wcschr()

Find character in wide-character string 

wcscmp()

Compare wide-character strings 

wcscpy()

Copy wide-character strings 

wcscspn()

Return span of one wide-character string not in another 

wcslen()

Get length of wide-character string 

wcsncat()

Concatenate wide-character strings to length n

wcsncmp()

Compare wide-character strings to length n

wcsncpy()

Copy wide-character strings to length n

wcspbrk()

Return pointer to one wide-character string in another 

wcsrchr()

Find character in wide-character string from right 

wcsrtombs()

Convert a wide-character string to a character string (restartable) 

wcsspn()

Return span of one wide-character string in another 

wcstod()

Convert wide-character string to double precision 

wcstok()

Move token through wide-character string 

wcstol()

Convert wide-character string to long integer 

wcstombs()

Convert wide-character string to multibyte string 

wcstoul()

Convert wide-character string to unsigned long integer 

wscwcs()

Find string in wide-character string 

wcswidth()

Determine number of column positions of a wide-character string 

wctob()

Wide character to single byte conversion 

wctomb()

Convert wide-character to multibyte character 

wcwidth()

Determine number of column positions of a wide character 

wscol()

Return display width of wide-character string 

wsdup()

Duplicate wide-character string 

The following table describes the formatted wide-character input and output in libc.

Table 2–13 Formatted Wide-character Input and Output in libc

Library Routine 

Description 

fwprintf()

Print formatted wide-character output 

fwscanf()

Convert formatted wide-character input 

swprintf()

Print formatted wide-character output 

swscanf()

Convert formatted wide-character input 

vfwprintf()

Wide-character formatted output of a stdarg argument list

vswprintf()

Wide-character formatted output of a stdarg argument list

wprintf()

Print formatted wide-character output 

wscanf()

Convert formatted wide-character input 

wsprintf()

Generate wide-character string according to format 

wsscanf()

Formatted input conversion 

This table describes the wide strings function APIs in libc.

Table 2–14 Wide Stringslibc

Library Routine 

Description 

wcsstr()

Find a wide-character substring 

wmemchr()

Find a wide character in memory 

wmemcmp()

Compare wide characters in memory 

wmemcpy()

Copy wide characters in memory 

wmemmove()

Copy wide characters in memory with overlapping areas 

wmemset()

Set wide characters in memory 

wscasecmp()

Compare wide-character strings, ignore case differences 

wsncasecmp()

Process code-string operations 

The following table describes the wide-character input and output in libc.

Table 2–15 Wide-Character Input and Output in libc

Library Routine 

Description 

fgetwc()

Get multibyte character from stream, convert to wide character 

fgetws()

Get multibyte string from stream, convert to wide character 

fputwc()

Convert wide character to multibyte character, puts to stream 

fputws()

Convert wide character to multibyte string, puts to stream 

fwide()

Set stream orientation 

getwchar()

Get multibyte character from stdin, convert to wide character

getws()

Get multibyte string from stdin, convert to wide character

putwchar()

Convert wide character to multibyte character, puts to stdin

putws()

Convert wide character to multibyte string, puts to stdin

ungetwc()

Push a wide character back into input stream