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.

Note: If a 64-bit locale is to be created, then meth_lib_path must specify the path for a single archive for the two shared objects, one 32-bit and the other 64-bit, containing the specified subroutines. Specifying separate paths to the 32-bit and 64-bit shared objects will result in localedef failing due to incompatible XCOFF format.

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:

Item	Description
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:

The number of bytes specified by the LenS parameter have been converted.
The number of characters specified by the LenPC parameter have been converted.
The byte value specified in the StopCh parameter is encountered in the input buffer pointed to by the S parameter.
An invalid or incomplete character is found in the input buffer pointed to by the S parameter.

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:

Conversion ceases.
The value specified by the StopCh parameter is placed in the PC parameter.
The EndPtr parameter is set to point immediately after the value specified by the StopCh parameter.
The Err parameter is set to 0.
The number of characters converted is returned.

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:

Item	Description
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:

Item	Description
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:

The number of wide characters specified by the LenPC parameter have been converted.
The number of bytes specified by the LenS parameter have been converted.
The character value specified in the StopCh parameter is encountered in the input buffer pointed to by the PC parameter.
An invalid wide character is found in the input buffer pointed to by the PC parameter.

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:

Conversion ceases.
The character specified by the StopCh parameter is placed at the end of the data currently pointed to by the S parameter.
The EndPtr parameter is set to point immediately after the character specified by the StopCh parameter.
The Err parameter is set to 0.
The number of bytes placed in the buffer pointed to by the S parameter is returned.

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:

Item	Description
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.

Files

Item	Description
/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.