Method files

Method files can be used when creating ASCII locales. They specify the method functions used by the C runtime's locale-sensitive interfaces when the ASCII locale is activated.

IBM ships the method files used to build its ASCII locales in the /usr/lib/nls/method directory. These method files support various ASCII Latin 1 and non-Latin 1 single byte encodings, ASCII SJIS and EUC multibyte encodings and UTF-8 multibyte encodings.

By replacing the CHARMAP related method functions in a method file, users can create a locale which supports a user-defined code page. For each replaced method, the method file supplies the user-written method function name, and optionally indicates where the method function code is to be found (.o file, archive library or DLL). The method source file maps method names to the National Language Support (NLS) subroutines that implement those methods. The method file also specifies the object libraries or DLL side decks where the implementing subroutines are stored. The methods correspond to those subroutines that require direct access to the data structures representing locale data.

Each user provided method must follow the standard interface defined for the API it implements and add an argument of type _LC_charmap_objhdl_t as the first argument. The _LC_charmap_objhdl_t is defined in the localdef.h header file.

Users can provide these CHARMAP methods via a DLL side deck, an archive library or an object file. The user-written method functions are used both by the locale-sensitive APIs they represent, and also by the localedef utility itself while generating the method-file based ASCII locale object. This second use by localedef itself causes a temporary DLL to be created while processing the CHARMAP file supplied on the -f parameter. The name of the file containing method objects or side deck information is passed by the localedef utility as a parameter on the c89 command line, so the standard archive/object/side deck suffix naming conventions apply (for example, .a, .o, .x).

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
   "is_wctype" meth_name meth_lib_path
   "mblen" meth_name meth_lib_path
   "mbstowcs" meth_name meth_lib_path
   "mbtowc" 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
   MBSTOWCS_932
   MBSTOWCS_EUCJP
   MBSTOWCS_SB
   MBTOWC_932
   MBTOWC_EUCJP
   MBTOWC_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 file containing the compiled subroutine or a side-deck for the DLL containing the subroutine.

mblen      mbstowcs
mbtowc     wcstombs
wcswidth   wctomb
wcwidth

mbtopc
mbstopcs
pctomb
pcstombs

Any other method not specified in the method file retains the default. Mixing of user-written method function names (represented as cfunc_name in the grammar) and IBM-provided method function names (represented by global_name in the grammar) is not allowed. A method file should not include both. If the localedef command encounters both cfunc_name values and global_name values in a method file, an error is generated and the locale is not created.

METHODS

 mblen "__mblen_myuni"
 mbstowcs "__mbstowcs_myuni" "/u/my/libmyuni.a"
 mbtowc "__mbtowc_myuni"
 wcstombs "__wcstombs_myuni" "/u/gen/libgenuni.a"
 wcswidth "__wcswidth_myuni"
 wctomb "__wctomb_myuni"
 wcwidth "__wcwidth_myuni" "./wcwidth.o"

c89 -o myuni.locale -Wl,xplink ./localefBGgfFcGAo
 ./localeEgaBGaahA.o /u/my/libmyuni.a
 /u/gen/libgenuni.a ./wcwidth.o

If an individual method does not specify a meth_lib_path name, the method inherits the most recently specified meth_lib_path name. If no meth_lib_path name is specified in the METHODS section, the default runtime library side-deck is assumed. The files indicated by meth_lib_path names of all methods in the method file are used when linking the locale object. A concatenated list of all meth_lib_path names is specified on the link step. If multiple object libraries or side decks are specified, the same routine should not be defined in more than one of them. Unexpected results may occur if the method functions appear in more than one file, particularly if the duplicate copies are not identical. The binder could resolve a method function from a file different from the one given in the method file itself.

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