[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Files Reference

Locale Method Source File Format

Purpose

Specifies the methods to be overridden when constructing a locale.

Description

The methods source file maps methods names to the National Language Support (NLS) subroutines that implement those methods. The methods file also specifies the libraries where the implementing subroutines are stored.

The methods correspond to those subroutines that require direct access to the data structures representing locale data.

The following is the expected grammar for a methods file:

method_def : "METHODS"
           | method_assign_list "END METHODS"
           ;
method_assign_list :
        method_assign_list method_assign
        | method_assign_list
        | method_assign
        ;
method_assign :
        "csid" meth_name meth_lib_path
        | "fnmatch" meth_name meth_lib_path
        | "get_wctype" meth_name meth_lib_path
        | "is_wctype" meth_name meth_lib_path
        | "mblen" meth_name meth_lib_path
        | "__mbstopcs" meth_name meth_lib_path
        | "mbstowcs" meth_name meth_lib_path
        | "__mbtopc" meth_name meth_lib_path
        | "mbtowc" meth_name meth_lib_path
        | "__pcstombs" meth_name meth_lib_path
        | "__pctomb" meth_name meth_lib_path
        | "regcomp" meth_name meth_lib_path
        | "regerror" meth_name meth_lib_path
        | "regexec" meth_name meth_lib_path
        | "regfree" meth_name meth_lib_path
        | "rpmatch" meth_name meth_lib_path
        | "strcoll" meth_name meth_lib_path
        | "strfmon" meth_name meth_lib_path
        | "strftime" meth_name meth_lib_path
        | "strptime" meth_name meth_lib_path
        | "strxfrm" meth_name meth_lib_path
        | "towlower" meth_name meth_lib_path
        | "towupper" meth_name meth_lib_path
        | "wcscoll" meth_name meth_lib_path
        | "wcsftime" meth_name meth_lib_path
        | "wcsid" meth_name meth_lib_path
        | "wcstombs" meth_name meth_lib_path
        | "wcswidth" meth_name meth_lib_path
        | "wcsxfrm" meth_name meth_lib_path
        | "wctomb" meth_name meth_lib_path
        | "wcwidth" meth_name meth_lib_path
        ;
meth_name: global_name
         | cfunc_name
         ;
global_name: "CSID_STD"
        | "FNMATCH_C"
        | "FNMATCH_STD"
        | "GET_WCTYPE_STD"
        | "IS_WCTYPE_SB"
        | "IS_WCTYPE_STD"
        | "LOCALECONV_STD"
        | "MBLEN_932"
        | "MBLEN_EUCJP"
        | "MBLEN_SB"
        | "__MBSTOPCS_932"
        | "__MBSTOPCS_EUCJP"
        | "__MBSTOPCS_SB"
        | "MBSTOWCS_932"
        | "MBSTOWCS_EUCJP"
        | "MBSTOWCS_SB"
        | "__MBTOPC_932"
        | "__MBTOPC_EUCJP"
        | "__MBTOPC_SB"
        | "MBTOWC_932"
        | "MBTOWC_EUCJP"
        | "MBTOWC_SB"
        | "NL_MONINFO"
        | "NL_NUMINFO"
        | "NL_RESPINFO"
        | "NL_TIMINFO"
        | "__PCSTOMBS_932"
        | "__PCSTOMBS_EUCJP"
        | "__PCSTOMBS_SB"
        | "__PCTOMB_932"
        | "__PCTOMB_EUCJP"
        | "__PCTOMB_SB"
        | "REGCOMP_STD"
        | "REGERROR_STD"
        | "REGEXEC_STD"
        | "REGFREE_STD"
        | "RPMATCH_C"
        | "RPMATCH_STD"
        | "STRCOLL_C"
        | "STRCOLL_SB"
        | "STRCOLL_STD"
        | "STRFMON_STD"
        | "STRFTIME_STD"
        | "STRPTIME_STD"
        | "STRXFRM_C"
        | "STRXFRM_SB"
        | "STRXFRM_STD"
        | "TOWLOWER_STD"
        | "TOWUPPER_STD"
        | "WCSCOLL_C"
        | "WCSCOLL_STD"
        | "WCSFTIME_STD"
        | "WCSID_STD"
        | "WCSTOMBS_932"
        | "WCSTOMBS_EUCJP"
        | "WCSTOMBS_SB"
        | "WCSWIDTH_932"
        | "WCSWIDTH_EUCJP"
        | "WCSWIDTH_LATIN"
        | "WCSXFRM_C"
        | "WCSXFRM_STD"
        | "WCTOMB_932"
        | "WCTOMB_EUCJP"
        | "WCTOMB_SB"
        | "WCWIDTH_932"
        | "WCWIDTH_EUCJP"
        | "WCWIDTH_LATIN"
        ;

Where cfunc_name is the name of a user supplied subroutine, and meth_lib_path is an optional path name for the library containing the specified subroutine.

The localedef command parses this information to determine the methods to be used for this locale. The following subroutines must be specified in the method file:

Any other method not specified in the method file retains the default.

Mixing of cfunc_name values and global_name values is not allowed. A method file should not include both. If the localedef command receives a method file containing both cfunc_name values and global_name values, an error is generated and the locale is not created.

It is not mandatory that the METHODS section specify the library name. If an individual method does not specify a library, the method inherits the most recently specified library. The libc.a library is the default library.

The method for the mbtowc and wcwidth subroutines should avoid calling other methods where possible.

An understanding of how the __mbtopc, __mbstopcs, __pctomb, and __pcstombs subroutines process wide characters is useful when constructing a method file. These subroutines should not be used in applications programs.

__mbtopc Subroutine

The __mbtopc subroutine converts a character to a process code.

The syntax for the __mbtopc subroutine is as follows:

size_t __mbtopc(PC, S, LenS, Err)
wchar_t *PC;
uchar *S;
size_t LenS;
int *Err;

The input buffer pointed to by the S parameter contains the number of bytes of character data specified in the LenS parameter. The __mbtopc subroutine attempts to convert the character to a process code. If a valid character is found in the input buffer pointed to by the S parameter, the character is converted and stored in the PC parameter, and the number of bytes in the character is returned.

If the number of bytes specified by the LenS parameter in the input buffer pointed to by the S parameter form an invalid character, the subroutine returns 0 and sets the Err parameter to the value -1. If a character cannot be formed in the number of bytes specified by the LenS parameter or less, the subroutine returns 0 and sets the Err parameter to the number of bytes required to form a character beginning with the data pointed to by the S parameter.

The parameters have the following values:

PC Points to a wide character to contain the converted character.
S Points to the buffer of character data to be converted.
LenS Specifies the number of bytes of character data pointed to by the S parameter.
Err Specifies an error value indicating why the conversion failed.

__mbstopcs Subroutine

The __mbstopcs subroutine converts a character string to a process code string.

The syntax for the __mbstopcs subroutine is as follows:

size_t __mbstopcs(PC, LenPC, S, LenS, StopCh, EndPtr, Err)
wchar_t *PC;
size_t LenPC;
uchar *S;
size_t LenS;
uchar StopCh;
uchar **EndPtr;
int *Err;

The input buffer pointed to by the S parameter contains the number of bytes of character data specified in the LenS parameter. The __mbstopcs subroutine attempts to convert the character data to process codes. The conversion of characters continues until one of the following occurs:

If the number of bytes specified by the LenS parameter or the number of characters specified by the LenPC parameter are successfully converted, the __mbstopcs subroutine returns the number of characters converted, sets the Err parameter to 0, and sets the EndPtr parameter to point immediately after the last character converted in the input buffer pointed to by the S parameter.

If the byte specified by the StopCh parameter is found in the input buffer pointed to by the S parameter, the following occurs:

If an invalid character is found in the input buffer pointed to by the S parameter, the EndPtr parameter is set to point to the start of this character, the Err parameter is set to (size_t)-1, and the __mbstopcs subroutine returns the number of characters converted.

If an incomplete character is found at the end of the input buffer pointed to by the S parameter, the EndPtr parameter is set to point to the start of the incomplete character, and the Err parameter is set to the number of bytes in a character starting with the byte pointed to by EndPtr parameter. The __mbstopcs subroutine returns the number of characters converted.

The parameters have the following values:

PC Points to a wchar_t array to contain the converted characters.
LenPC Specifies the maximum number of wide characters that can be placed in the PC parameter.
S Points to a buffer of character data to be converted.
LenS Specifies the number of bytes of character data in the S parameter.
StopCh Specifies a single-byte character value to indicate end of data in the S parameter.
EndPtr Points into the S parameter where character conversion ended.
Err Specifies an error value indicating why the conversion failed.

__pctomb Subroutine

The __pctomb subroutine converts a process code to a character.

The syntax for the __pctomb subroutine is as follows:

size_t __pctomb(S, LenS, PC, Err)
char *S;
size_t LenS;
wchar_t *PC;
int *Err;

The input buffer pointed to by the PC parameter contains a wide character that the subroutine attempts to convert to a character in the input buffer pointed to by the S parameter. If a valid process code is found in the input buffer pointed to by the PC parameter, it is converted and stored in the input buffer pointed to by the S parameter, and the number of bytes in the character is returned.

If the wide character in the input buffer pointed to by the PC parameter is invalid, the __pctomb subroutine returns 0 and sets the Err parameter to the value (size_t)-1. If the length of the character is greater than the number of bytes specified by the LenS parameter, the __pctomb subroutine returns 0 and sets the Err parameter to the number of bytes required to form the character.

The parameters have the following values:

S Points to a buffer to contain the converted process code.
LenS Specifies the size of the character array pointed to by the S parameter.
PC Points to the wide character to be converted.
Err Specifies an error value indicating why the conversion failed.

__pcstombs Subroutine

The __pcstombs subroutine converts a wide character string to a character string.

The syntax for the __pcstombs subroutine is as follows:

size_t __pcstombs(S, LenS, PC, LenPC, StopCh, EndPtr, Err)
char *S;
size_t LenS;
wchar_t *PC;
size_t LenPC;
wchar_t StopCh;
char **EndPtr;
int *Err;

The input buffer pointed to by the PC parameter contains the number of wide characters specified by the LenPC parameter. The __pcstombs subroutine attempts to convert the process codes to characters. The conversion continues until one of the following occurs:

If the number of bytes specified by the LenS parameter or the number of characters specified by the LenPC parameter are successfully converted, the __pcstombs subroutine returns the number of bytes placed in the buffer pointed to by the S parameter, sets the Err parameter to 0, and sets the EndPtr parameter to point immediately after the last character converted in the input buffer pointed to by the PC parameter.

If the character specified by the StopCh parameter is found in the input buffer pointed to by the PC parameter, the following occurs:

If an invalid wide character is found in the input buffer pointed to by the PC parameter, the EndPtr parameter is set to point to the start of this character, the Err parameter is set to (size_t)-1, and the __pcstombs subroutine returns the number of bytes placed in the buffer pointed to by the S parameter.

The parameters have the following values:

S Points to a buffer to contain the converted data.
LenS Specifies the size in bytes of the character array pointed to by the S parameter.
PC Points to a wchar_t array to be converted.
LenPC Specifies the number of wide characters in the array pointed to by the PC parameter.
StopCh Specifies a wide-character value to indicate end of data in the array pointed to by the PC parameter.
EndPtr Points into the S parameter where character conversion ended.
Err Specifies the error value indicating why the conversion failed.

Implementation Specifics

This source file format is part of the Base Operating System (BOS) Runtime.

Files

/usr/lib/nls/loc/* Specifies locale definition source files for supported locales.
/usr/lib/nls/charmap/* Specifies character set description (charmap) source files for supported locales.

Related Information

The locale command, localedef command.

Character Set Description (charmap) Source File Format , Locale Definition Source File Format .

For specific information about other locale categories and their keywords, see the LC_COLLATE category, LC_CTYPE category, LC_MESSAGES category, LC_MONETARY category, LC_NUMERIC, and LC_TIME category for the locale definition source file format.

Changing Your Locale, Locale Overview for System Management, National Language Support Overview for System Management, Understanding the Locale Definition Source File in AIX Version 4.3 System Management Concepts: Operating System and Devices.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]