• A character map source file (charmap)

  The charmap(4) reference page explains the format and rules for this file. This chapter includes a charmap example that conforms to binary character encodings specified for the ISO Latin-1 codeset, which defines all characters as single 8-bit bytes. The chapter also includes an example that shows part of a charmap file for the SJIS codeset, which defines both single-byte and multibyte characters.

• A locale source file

  The locale(4) reference page explains the rules and format for this file. This chapter develops a locale named de_DE.ISO8859-1@example that supports the language and customs of Germany.

• A methods file with associated shareable library

  These files are required when the charmap file defines multibyte characters; otherwise, the files are optional. The methods file specifies the shareable library that contains redefinitions of the C Library interfaces that convert data to and from internal process (wide-character) encoding.

LC_MESSAGES    (1)
yesexpr         "^[<j><J>][[:alpha:]]*"    (2)
noexpr          "^[<n><N>][[:alpha:]]*"    (3)
yesstr          "<j>"   (4)
nostr           "<n>"   (5)
END LC_MESSAGES    (6)

LC_NUMERIC   (1)
decimal_point                   "<,>"   (2)
thousands_sep                   "<.>"   (3)
grouping                        3    (4)
END LC_NUMERIC   (5)

1. Category header

2. Definition of radix character (decimal point)

3. Definition of character used to separate groups of digits to the left of the radix character

4. The size of each group of digits to the left of the radix character

5. Category trailer

The preceding example shows all of the symbols you can define in the LC_NUMERIC section. In place of any symbol definitions, you can specify a copy statement between the section header and trailer to include this section from another locale.

Refer to the locale(4) reference page for detailed rules about symbol definitions.

LC_TIME    (1)

abday    "<S><o>";"<M><o>";"<D><i>";"<M><i>";"<D><o>";\
         "<F><r>";"<S><a>"    (2)

day      "<S><o><n><n><t><a><g>";"<M><o><n><t><a><g>";\
         "<D><i><e><n><s><t><a><g>";\
         "<M><i><t><t><w><o><c><h>";\
         "<D><o><n><n><e><r><s><t><a><g>";\
         "<F><r><e><i><t><a><g>";"<S><a><m><s><t><a><g>"    (3)

abmon    "<J><a><n>";"<F><e><b>";"<M><a:><r>";\
         "<A><p><r>";"<M><a><i>";"<J><u><n>";\
         "<J><u><l>";"<A><u><g>";"<S><e><p>";\
         "<O><k><t>";"<N><o><v>";"<D><e><z>"    (4)

mon      "<J><a><n><u><a><r>";"<F><e><b><r><u><a><r>";\
         "<M><a:><r><z>";"<A><p><r><i><l>";"<M><a><i>";\
         "<J><u><n><i>";"<J><u><l><i>";\
         "<A><u><g><u><s><t>";\
         "<S><e><p><t><e><m><b><e><r>";\
         "<O><k><t><o><b><e><r>";\
         "<N><o><v><e><m><b><e><r>";\
         "<D><e><z><e><m><b><e><r>"    (5)

d_t_fmt  "%d.%B %Y %H:%M:%S"    (6)

.
.
.

END LC_TIME    (7)

1. Section header

2. Abbreviated names for days of the week

   Use the %a conversion specifier to include this string in formats.

3. Full names for days of the week

   Use the %A conversion specifier to include this string in formats.

4. Abbreviated names for months of the year

   Use the %b conversion specifier to include this string in formats.

5. Full names for months of the year

   Use the %B conversion specifier to include this string in formats.

6. Format for combined date and time information

   Use this format to combine field descriptors (whose first character is the percent sign (%)) and symbols for characters. You can specify characters from the Portable Character Set (PCS), such as the period (.) and ASCII space, explicitly as characters rather than implicitly through symbols; however, use symbols to specify all other characters.

   The specified format includes the field descriptors for the day of the month (%d), the full name of the month (%B), the full representation of the year (%Y), the number of hours in a 24-hour period (%H), the number of minutes (%M), and the number of seconds (%S). If the date were December 12, 1993, and the time 29 seconds after 12 o'clock in the afternoon, the format specified in this example would cause the date command to display 12.Dezember 1993 12:00:29.

7. Section trailer

The preceding example includes only some of the symbol definitions that are standard for the LC_TIME category. The following definitions are also standard:

Only locales with multibyte codesets must use methods. When a locale uses methods, there are some methods that the locale must supply and other methods that it can optionally supply. A method is required when the corresponding interface is converting characters between data formats and needs codeset-specific logic to do that operation correctly. A method is optional when the corresponding interface is working with data after it has been converted to wide-character format and can apply logic that is valid for both single-byte and multibyte characters.

Methods must be available on the system in a shareable library. This library and the functions that implement each method in the library are made known to the localedef command through a methods file. When the localedef command processes the methods file along with the charmap and locale source files, the resulting locale includes pointers to all methods that are supplied with the locale, along with pointers to default implementations for optional methods that are not supplied with the locale. When you set the LANG variable to the newly built locale and run a command or application, methods are used wherever they have been enabled in the system software.

• __mbstopcs

• __mbtopc

• __pcstombs

• __pctomb

• mblen

• mbstowcs

• mbtowc

• wcstombs

• wctomb

• wcswidth

• wcwidth

#include <stdlib.h>  (1)
#include <wchar.h>   
#include <sys/localedef.h>   

/*
The algorithm for this conversion is:
s[0] < 0x9f:  PC = s[0]
s[0] = 0x8e:  PC = s[1] + 0x5f;
s[0] = 0x8f   PC = (((s[1] - 0xa1) << 7) | (s[2] - 0xa1)) + 0x303c
s[0] > 0xa1:0xa1 < s[1] < 0xfe
              PC = (((s[0] - 0xa1) << 7) | (s[1] - 0xa1)) + 0x15e
            0x21 < s[1] < 0x7e
              PC = (((s[0] - 0xa1) << 7) | (s[1] - 0x21)) + 0x5f1a
+-----------------+-----------+-----------+-----------+
|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)
int  __mbtopc_sdeckanji(
        wchar_t *pwc,   (3)
        char *ts,   (4)
        size_t maxlen,   (5)
        int *err,   (6)
        _LC_charmap_t *handle )   (7)
{
    wchar_t dummy;   (8)
    unsigned char *s = (unsigned char *)ts;   (9)
    if (s == NULL)
        return(0);   (10)
    if (pwc == (wchar_t *)NULL)
        pwc = &dummy;   (11)
    *err = 0;   (12)
    if (s[0] <= 0x8d) {
        if (maxlen < 1) {
            *err = 1;
            return(0);
        }
        else {
            *pwc = (wchar_t) s[0];
            return(1);
        }
    }   (13)
    else if (s[0] == 0x8e) {
        if (maxlen >= 2) {
            if (s[1] >=0xa1 && s[1] <=0xfe) {
                *pwc = (wchar_t) (s[1] + 0x5f);
                return(2);
            }
        }
        else {
            *err = 2;
            return(0);
        }
    }   (14)
    else if (s[0] == 0x8f) {
        if (maxlen >= 3) {
            if ((s[1] >=0xa1 && s[1] <=0xfe) &&
                (s[2] >=0xa1 && s[2] <= 0xfe)) {
                *pwc = (wchar_t) (((s[1] - 0xa1) << 7) |
                       (wchar_t) (s[2] - 0xa1)) + 0x303c;
                return(3);
            }
        }
        else {
            *err = 3;
            return(0);
        }
    }   (15)
    else if (s[0] <= 0x9f) {
        if (maxlen < 1) {
            *err = 1;
            return(0);
        }
        else {
            *pwc = (wchar_t) s[0];
            return(1);
        }
    }   (16)
    else if (s[0] >= 0xa1 && s[0] <= 0xfe) {
        if (maxlen >= 2) {
            if  (s[1] >=0xa1 && s[1] <= 0xfe) {
                *pwc = (wchar_t) (((s[0] - 0xa1) << 7) |
                       (wchar_t) (s[1] - 0xa1)) + 0x15e;
                return(2);
            } else if  (s[1] >=0x21 && s[1] <= 0x7e) {
                *pwc = (wchar_t) (((s[0] - 0xa1) << 7) |
                       (wchar_t) (s[1] - 0x21)) + 0x5f1a;
                return(2);
            }
        }
        else {
            *err = 2;
            return(0);
        }
    }   (17)
    *err = -1;
    return(0);   (18)
}

1. Include header files that contain constants and structures required for this method.

2. Describes the algorithm used to determine the number of bytes and valid byte combinations for the different character sets that the codeset supports.

   The codeset supports several character sets and each set contains characters of only one length. The value in the first byte indicates the character set and therefore the character length. For character sets with multibyte characters, one or more additional bytes must be examined to determine whether the value sequence identifies a character or is invalid.

3. Points, through pwc, to a buffer that stores the wide character.

4. Points, through ts, to a buffer that stores the bytes that are passed to the method from the calling function.

5. Declares a variable, maxlen, that stores the maximum number of bytes in the multibyte data.

   This value is passed by the calling function.

6. Points, through err, to a buffer that stores execution status.

7. Points, through handle, to a structure that contains pointers to the methods that parse the character maps for this locale.

8. Declares a variable, dummy, to which pwc can be set to ensure a valid address.

9. Casts ts (an array of signed characters) to s (an array of unsigned characters).

   This operation prevents problems when integer values are stored in the array and then referenced by index. Compilers apply sign extension to values when comparing a small signed data type, such as int, to a large signed data type, such as char. Sign extension means that the high bit of the value in the small data type is used to fill in bits that remain when the value is converted to the larger data type for comparison. For example, if s[0] is the value 0x8e, sign extension would cause it to be treated as 0xffffff8e. In this case, a condition like the following one would be evaluated as true when you would expect it to be false:

   if (s[0] <= 0x8d

10. Returns zero (0) if the s buffer contains or points to NULL.

11. Stores the contents of dummy in the wide-character buffer if the ts buffer contains or points to NULL.

    This operation ensures that *pwc always points to a valid address; otherwise, an application could produce a segmentation fault by referring to this pointer when a wide character has not been stored in pwc.

12. Initializes err to zero (0) to indicate success.

13. Determines if the character is one of the single-byte characters that the codeset defines for values equal to or less than 0x8d.

    If s contains no characters, returns zero (0) to indicate that no bytes were converted and sets err to 1 to indicate that 1 byte is needed to form a valid character.

    If the byte value is in the range being tested, moves the associated process code value to pwc and returns 1 to indicate the number of bytes converted.

14. Determines if the character is one of the double-byte characters that the codeset defines for the value 0x8e (first byte) and the value range 0xa1 to 0xfe (second byte).

    If yes, moves the associated process code value to the pwc buffer and returns 2 to indicate the number of bytes converted; otherwise, returns 0 to indicate that no conversion took place and sets err to 2 to specify that at least 2 bytes are needed to form a valid character.

15. Determines if the character is one of the triple-byte characters that the codeset defines for the value 0x8f (first byte), the range 0xa1 to 0xfe (second byte), and the range 0xa1 to 0xfe (third byte).

    If yes, moves the associated process code value to pwc and returns 3 to indicate the number of bytes converted; otherwise, sets err to 3 to indicate that at least 3 bytes are needed and returns zero (0) to indicate that no character was converted.

16. Determines if the character is one of the single-byte characters that the codeset defines for the range 0x90 to 0x9f.

    If there are no bytes in the standard I/O buffer, returns zero (0) to indicate that no bytes were converted and sets err to 1 to indicate that at least 1 byte is needed to form a valid character.

    If the byte value is in the defined range, moves the associated process code value to pwc and returns 1 to indicate the number of bytes converted.

17. Determines if the character is one of the double-byte characters that the codeset defines for the range 0xa1 to 0xfe (first byte) and 0x21 to 0x7e (second byte).

    If yes, moves the associated process code value to pwc buffer and returns 2 to indicate the number of bytes converted; otherwise, sets err to 2 to indicate that at least 2 bytes are needed to form a valid character and returns zero (0) to indicate that no bytes were converted.

18. Sets err to -1 to indicate that an invalid multibyte sequence was encountered and returns zero (0) to indicate that no bytes were converted.

    These statements execute if the multibyte data in s satisfies none of the preceding if conditions.

int __pcstombs_sdeckanji()
{
        return -1;   (1)
}

1. Returns -1 to indicate that the locale does not support the method.

   This return causes the fputws() function to use multiple calls to putwc() to convert wide characters in the string.

If you choose to implement this method fully rather than writing it to return -1, your function implementation returns the number of wide characters converted and must include header files and parameters as shown in the following example:

#include <stdlib.h>
#include <wchar.h>
#include <sys/localedef.h>

int __pcstombs_newcodeset(
        wchar_t *pcsbuf,   (1)
        size_t pcsbuf_len,   (2)
        char *mbsbuf,  (3)
        size_t mbsbuf_len,  (4)
        char **endptr,  (5)
        int *err,   (6)
        _LC_charmap_t *handle )  (7)

1. Specifies a pointer to a buffer that contains the wide-character string.

2. Specifies a variable with the length of the wide-character buffer.

   This value is passed to the method on the call from fputws().

3. Specifies a pointer to a buffer that contains the multibyte-character string.

4. Specifies a variable with the length of the multibyte-character buffer.

   This value is passed to the method on the call from fputws().

5. Points, through endptr, to a pointer to the byte position in the multibyte-character buffer where the next character would begin if multiple calls to fputws() are required to convert all the wide-character data.

6. Specifies a pointer to the execution status return.

   If this method calls the wctomb method to perform the character conversion, the wctomb method sets this status. Otherwise, this method must incorporate the logic to perform wide-character to multibyte-character conversion and set the status directly.

   In any event, the fputws() function expects the following values:

   • 0 for success

   • -1 to indicate that the wide-character value is invalid and therefore cannot be converted

   • A positive value to indicate that the multibyte-character buffer contains too few bytes after the last character to store the next character

     In this case, the value is the number of bytes required to store the next character. The fputws() function can then empty the multibyte-character buffer and try again.

7. Specifies a pointer to the _LC_charmap_t structure that stores pointers to the methods used with this locale.

int __pctomb_sdeckanji()
{
        return -1;   (1)
}

1. Returns -1 to indicate that the locale does not support this method.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/errno.h>   
#include <sys/localedef.h>   

/*
The algorithm for this conversion is:

s[0] < 0x9f:  1 byte
s[0] = 0x8e:  2 bytes
s[0] = 0x8f   3 bytes
s[0] > 0xa1   2 bytes

|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)

int __mblen_sdeckanji(
        char *fs,   (3)
        size_t maxlen,   (4)
        _LC_charmap_t *handle )   (5)
{
    const unsigned char *s = (void *) fs;   (6)

    if (s == NULL || *s == '\0')
        return(0);   (7)

    if (maxlen < 1) {
        _Seterrno(EILSEQ);
        return((size_t)-1);
    }   (8)

    if (s[0] <= 0x8d)
        return(1);   (9)

    else if (s[0] == 0x8e) {
        if (maxlen >= 2 && s[1] >=0xa1 && s[1] <=0xfe)
            return(2);
    }   (10)

    else if (s[0] == 0x8f) {
        if(maxlen >=3 && (s[1] >=0xa1 && s[1] <=0xfe) &&
            (s[2] >=0xa1 && s[2] <= 0xfe))
            return(3);
    }   (11)

    else if (s[0] <= 0x9f)
        return(1);   (12)

    else if (s[0] >= 0xa1) {
            if (maxlen >=2 && (s[0] <= 0xfe) )
                    if ( (s[1] >=0xa1 && s[1] <= 0xfe) ||
                       (s[1] >=0x21 && s[1] <= 0x7e) )
                        return(2);
    }   (13)

    _Seterrno(EILSEQ);
    return((size_t)-1);   (14)
}

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/localedef.h>  

size_t __mbstowcs_sdeckanji(
        wchar_t *pwcs,   (2)
        const char *s,   (3)
        size_t n,   (4)
        _LC_charmap_t *handle )   (5)
{
    int len = n;   (6)
    int rc;   (7)
    int cnt;   (8)
    wchar_t *pwcs0 = pwcs;   (9)
    int mb_cur_max;   (10)

    if (s == NULL)
        return (0);   (11)

    mb_cur_max = MB_CUR_MAX;   (12)

    if (pwcs == (wchar_t *)NULL) {
        cnt = 0;
        while (*s != '\0') {
             if ((rc = __mblen_sdeckanji(s, mb_cur_max, handle)) == -1)
                return(-1);
             cnt++  ;
             s += rc;
        }
        return(cnt);
    }   (13)

    while (len-- > 0) {
        if ( *s == '\0') {
            *pwcs = (wchar_t) '\0';
            return (pwcs - pwcs0);
        }
        if ((cnt = __mbtowc_sdeckanji(pwcs, s, mb_cur_max, handle)) < 0)
            return(-1);
        s += cnt;
        ++pwcs;
    }   (14)

    return (n);   (15)
}

1. Include header files that contain constants and structures required for this method.

2. Points, through pwcs, to a buffer that contains the wide-character string.

3. Points, through s, to a buffer that contains the multibyte-character string.

4. Defines a variable, n, that contains the number of wide characters in pwcs.

5. Points, through handle, to a structure that stores pointers to the methods that parse character maps for this locale.

6. Assigns the number of wide characters in the pwcs buffer (the n value supplied by the calling function) to len.

7. Defines a variable, rc, that stores the return count from a call this method makes to the mblen function.

8. Defines a variable, cnt, that counts the bytes used by characters in the s buffer.

9. Saves the start of the wide-character string passed by the calling function in the pwcs0 variable.

10. Defines a variable, mb_cur_max, that is later set to MB_CUR_MAX and used in a call to the mblen method.

11. Returns zero (0) if s is null. A method should return zero (0) if the locale's character encoding is stateless and a nonzero value if the locales's character encoding is stateful.

12. Assigns the value defined for MB_CUR_MAX to mb_cur_max for use on the following call to the mblen method.

13. Checks to see if a null pointer was passed from the calling function and, if yes, calls the mblen method to calculate the size of the wide-character string.

    The programmer can request the size of the pwcs buffer (for memory allocation purposes) by passing a null wide character as the pwcs parameter in the call to mbstowcs(). The programmer can then use the return value to efficiently allocate memory space for the application's wide-character buffer before calling mbstowcs() again to actually convert the multibyte string.

14. Converts bytes in the multibyte-character buffer by calling the __mbtowc method until a null character (end-of-string) is encountered.

    Stops processing and returns the number of wide characters in the pwcs buffer if a NULL is encountered; increments the byte position in the multibyte character buffer by an appropriate number each time a character is successfully converted.

    This while loop uses the condition len-- > 0 to ensure that processing stops when the pwcs buffer is full. The first if condition in the loop makes sure that, if the multibyte string in the s buffer is null terminated, the associated null terminator in the pwcs buffer is not included in the wide-character count that the mbtowcs() function returns to the application.

15. Returns the value in n to indicate the resultant number of wide characters in the pwcs buffer.

    This statement executes if the pwcs buffer runs out of space before a NULL is encountered in the s buffer.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/errno.h>   
#include <sys/localedef.h>   

/*
The algorithm for this conversion is:

s[0] < 0x9f:  PC = s[0]
s[0] = 0x8e:  PC = s[1] + 0x5f;
s[0] = 0x8f   PC = (((s[1] - 0xa1) << 7) | (s[2] - 0xa1)) + 0x303c
s[0] > 0xa1:0xa1 < s[1] < 0xfe
              PC = (((s[0] - 0xa1) << 7) | (s[1] - 0xa1)) + 0x15e
0x21 < s[1] < 0x7e
              PC = (((s[0] - 0xa1) << 7) | (s[1] - 0x21)) + 0x5f1a

+-----------------+-----------+-----------+-----------+
|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)
int __mbtowc_sdeckanji(
        wchar_t *pwc,   (3)
        const char *ts,   (4)
        size_t maxlen,   (5)
        _LC_charmap_t *handle )   (6)
{
    unsigned char *s = (unsigned char *)ts;   (7)
    wchar_t dummy;   (8)

    if (s == NULL)
        return(0);   (9)

    if (maxlen < 1) {
        _Seterrno(EILSEQ);
        return((size_t)-1);
    }   (10)

    if (pwc == (wchar_t *)NULL)
        pwc = &dummy;   (11)

    if (s[0] <= 0x8d) {
        *pwc = (wchar_t) s[0];
        if (s[0] != '\0')
            return(1);
        else
            return(0);
    }   (12)

    else if (s[0] == 0x8e) {
        if ( (maxlen >= 2) && ((s[1] >=0xa1) && (s[1] <=0xfe))) {
            *pwc = (wchar_t) (s[1] + 0x5f); /* 0x100 - 0xa1 */
            return(2);
        }
    }   (13)

    else if (s[0] == 0x8f) {
        if((maxlen >= 3) && (((s[1] >=0xa1) && (s[1] <=0xfe))
           && ((s[2] >=0xa1) && (s[2] <= 0xfe)))) {
                *pwc = (wchar_t) (((s[1] - 0xa1) << 7) |
                   (wchar_t) (s[2] - 0xa1)) + 0x303c;
           return(3);
        }
    }   (14)

    else if (s[0] <= 0x9f) {
        *pwc = (wchar_t) s[0];
        if (s[0] != '\0')
            return(1);
        else
            return(0);
    }   (15)

    else if (((s[0] >= 0xa1) && (s[0] <= 0xfe)) && (maxlen >= 2)){
            if (((s[1] >=0xa1) && (s[1] <= 0xfe))){
                    *pwc = (wchar_t) (((s[0] - 0xa1) << 7) |
                              (wchar_t)(s[1] - 0xa1)) + 0x15e;
                    return(2);
            } else if (((s[1] >=0x21) && (s[1] <= 0x7e))){
                    *pwc = (wchar_t) (((s[0] - 0xa1) << 7) |
                              (wchar_t)(s[1] - 0x21)) + 0x5f1a;
                    return(2);
            }
    }   (16)
    _Seterrno(EILSEQ);
    return(-1);   (17)
}

1. Includes header files that contain constants and structures required for this method.

2. Describes the algorithm used to determine the number of bytes in the character and whether it is a valid byte sequence.

   The codeset supports several character sets and each set contains characters of only one length. The value in the first byte indicates the character set and therefore the character length. For character sets with multibyte characters, one or more additional bytes must be examined to determine whether the value sequence identifies a character or is invalid.

3. Points, through pwc, to a buffer that contains the wide character.

4. Points, through ts, to a buffer that contains values in multibyte-character format.

5. Defines a variable, maxlen, that stores the maximum length of a multibyte character.

   This value is passed from the calling function; the value will have been set to MB_CUR_MAX on the original call made by the application programmer.

6. Points, through handle, to a structure that stores pointers to the methods that parse character maps for this locale.

7. Casts ts (an array of signed characters) to s (an array of unsigned characters).

   This operation prevents problems when integer values are stored in the array and then referenced by index. Compilers apply sign extension to values when comparing a small signed data type, such as int, to a large signed data type, such as char. Sign extension means that the high bit of the value in the small data type is used to fill in bits that remain when the value is converted to the larger data type for comparison. For example, if s[0] is the value 0x8e, sign extension would cause it to be treated as 0xffffff8e. In this case, a condition like the following one would be evaluated as true when you would expect it to be false:

   if (s[0] <= 0x8d

8. Defines a variable, dummy, that can be assigned to pwc to ensure pwc points to a valid address.

9. Returns zero (0) to indicate that the locale's character encoding is stateless if s contains or points to NULL.

   If passed a null pointer, this method should return a value to indicate whether the locale's character encoding is stateful or stateless. Return a nonzero value if your locale's character encoding is stateful.

10. Returns -1 cast to size_t and sets errno to EILSEQ (invalid byte sequence) if the multibyte data buffer is less than 1 byte in length.

11. Stores the contents of dummy in the wide-character buffer if the ts buffer contains or points to NULL.

    This operation ensures that pwc always points to a valid address; otherwise, an application could produce a segmentation fault by referring to this pointer when a wide character has not been stored in pwc.

12. Determines if the first byte identifies a single-byte character whose value is equal to or less than 0x8d.

    If yes, stores the associated process code value in the pwc buffer and returns 1 to indicate that the character length is 1 byte.

13. Determines if the first byte identifies a double-byte character whose first byte contains the value 0x8e and second byte contains a value in the range 0xa1 to 0xfe.

    If yes, stores the associated process code value in the pwc buffer and returns 2 to indicate that the character length is 2 bytes.

14. Determines if the first byte identifies a triple-byte character whose first byte contains the value 0x8f and whose second and third bytes contain a value in the range 0xa1 to 0xfe.

    If yes, stores the associated process code value in the pwc buffer and returns 3 to indicate that the character length is 3 bytes.

15. Determines if the first byte identifies a single-byte character whose value is equal to or less than 0x9f.

    If yes, stores the associated process code value in the pwc buffer and returns 1 to indicate that the character length is 1 byte.

16. Determines if the first byte identifies a double-byte character whose first byte contains a value in the range x0a1 to x0fe and whose second byte contains a value in the range 0x21 to 0x7e.

    If yes, stores the associated process code value in the pwc buffer and returns 2 to indicate that the character length is 2 bytes.

17. Returns -1 and sets errno to EILSEQ to indicate that an invalid multibyte sequence was encountered.

    These statements execute if the multibyte data in the s buffer satisfies none of the preceding if conditions.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <limits.h>   
#include <sys/localedef.h>   

size_t __wcstombs_sdeckanji(
        char *s,   (2)
        const wchar_t *pwcs,   (3)
        size_t n,   (4)
        _LC_charmap_t *handle )   (5)
{
    int cnt=0;   (6)
    int len=0;   (7)
    int i=0;   (8)
    char tmps[MB_LEN_MAX+1];   (9)

    if ( s == (char *)NULL) {
        cnt = 0;
        while (*pwcs != (wchar_t)'\0') {
            if ((len = __wctomb_sdeckanji(tmps, *pwcs)) == -1)
                    return(-1);
            cnt += len;
            pwcs++;
        }
        return(cnt);
    }   (10)

    if (*pwcs == (wchar_t)'\0') {
        *s = '\0';
        return(0);
    }   (11)

    while (1) {   (12)

        if ((len = __wctomb_sdeckanji(tmps, *pwcs)) == -1)
            return(-1);   (13)

        else if (cnt+len > n) {
            *s = '\0';
            break;
        }   (14)

        if (tmps[0] == '\0') {
            *s = '\0';
            break;
        }   (15)

        for (i=0; i<len; i++) {
            *s = tmps[i];
            s++;
        }   (16)

        cnt += len;   (17)

        if (cnt == n)
            break;   (18)

        pwcs++;   (19)
    }   (20)

    if (cnt == 0)
        cnt = len;   (21)
    return (cnt);   (22)
}

1. Include header files that contain constants and structures required for this method.

2. Points, through s, to a buffer that stores the multibyte-character string that this method passes to the calling function.

3. Points, through pwcs, to a buffer that stores the wide-character string that is being converted.

4. Defines a variable, n, that stores the number of maximum number of bytes in the multibyte-character string buffer.

   This value is supplied by the calling function.

5. Points, through handle, to a structure that points to the methods that parse character maps for this locale.

6. Initializes a variable, cnt, that is incremented by the number of bytes (len) of each converted character.

7. Initializes a variable, len, that stores the length of each converted character.

8. Initializes a variable, i, that is used to index the bytes in each multibyte character when moving a converted character from temporary storage to s.

9. Defines a temporary buffer, tmps, that stores the multibyte character returned to this method from a call to the wctomb method.

10. Checks to see if a NULL was passed from the calling function in the s buffer.

    If yes, calls the wctomb method to calculate the number of bytes required for converted characters (excluding the null terminator) in the multibyte-character buffer.

    The programmer can request the size of the s buffer (for memory allocation purposes) by passing a null byte as the data in the s parameter on the call to wcstombs(). The programmer can then use the return value to efficiently allocate memory space for the application's wide-character buffer before calling wcstombs() again to actually convert the wide-character string.

11. Returns zero (0) to indicate that no multibyte characters resulted and sets s to NULL if pwcs points to NULL.

12. Starts a while loop to process characters in the wide-character string.

13. Converts characters in the wide-character buffer by calling the wctomb method; returns -1 to indicate an invalid character if wctomb returns -1.

14. Terminates s with NULL and breaks out of the while loop if there is no room in s for the character just converted by wctomb.

15. Moves a null terminator to s and breaks out of the while loop when a NULL is encountered in s.

16. Appends each byte in tmps to s if the current wide character is not a null.

17. Increments cnt by the number of bytes (len) occupied by this character in multibyte format.

18. Breaks out of the while loop without adding a null terminator if the number of bytes processed equals n (the maximum number of bytes in s).

19. Increments pwcs to point to the next wide character to be converted.

20. Ends the while loop that converts each wide character.

21. Ensures that zero (0) is returned if s does not contain enough space for even one character.

22. Returns the number of bytes in the resultant multibyte-character string.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/errno.h>   
#include <sys/localedef.h>   

/*
  The algorithm for this conversion is:

PC <= 0x009f:                 s[0] = PC
PC >= 0x0100 and PC <=0x015d: s[0] = 0x8e
                              s[1] = PC - 0x005f
PC >= 0x015e and PC <=0x303b: s[0] = ((PC - 0x015e) >> 7) + 0x00a1
                              s[1] = ((PC - 0x015e) & 0x007f) + 0x00a1
PC >= 0x303c and PC <=0x5f19: s[0] = 0x8f
                              s[1] = ((PC - 0x303c) >> 7) + 0x00a1
                              s[2] = ((PC - 0x303c) & 0x007f) + 0x00a1
PC >= 0x5f1a and PC <=0x8df7  s[0] = ((PC - 0x5f1a) >> 7) + 0x00a1
                              s[1] = ((PC - 0x5f1a) & 0x007f) + 0x0021

+-----------------+-----------+-----------+-----------+
|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)

int __wctomb_sdeckanji(
        char *s,    (3)
        wchar_t wc,    (4)
        _LC_charmap_t *handle )    (5)
{
    if (s == (char *)NULL)
        return(0);    (6)

    if (wc <= 0x9f) {
        s[0] = (char) wc;
        return(1);
    }    (7)

    else if ((wc >= 0x0100) && (wc <= 0x015d)) {
        s[0] = 0x8e;
        s[1] = wc - 0x5f;
        return(2);
    }    (8)

    else if ((wc >=0x015e) && (wc <= 0x303b)) {
        s[0] = (char) (((wc - 0x015e) >> 7) + 0x00a1);
        s[1] = (char) (((wc - 0x015e) & 0x007f) + 0x00a1);
        return(2);
    }    (9)

    else if ((wc >=0x303c) && (wc <= 0x5f19)) {
        s[0] = 0x8f;
        s[1] = (char) (((wc - 0x303c) >> 7) + 0x00a1);
        s[2] = (char) (((wc - 0x303c) & 0x007f) + 0x00a1);
        return(3);
    }    (10)

    else if ((wc >=0x5f1a) && (wc <= 0x8df7)) {
        s[0] = (char) (((wc - 0x5f1a) >> 7) + 0x00a1);
        s[1] = (char) (((wc - 0x5f1a) & 0x007f) + 0x0021);
        return(2);
    }    (11)

    _Seterrno(EILSEQ);
    return(-1);    (12)
}

1. Include header files that contain constants and structures required for this method.

2. Describes the conversion algorithm that this method uses.

   Each character set supported by the codeset corresponds to a unique range of wide-character (process code) values and, within each character set, multibyte characters are of uniform length (1, 2, or 3 bytes). Therefore, the range in which each wide-character value falls indicates the number of bytes required for the character in multibyte format; the wide-character value itself determines the specific byte value or values for the character in multibyte format.

3. Points, through s, to a buffer that stores the multibyte character.

4. Defines the wc variable that stores the wide character.

5. Points, through handle, to a structure that stores pointers to the methods that parse the character maps for this locale.

6. Returns zero (0) to indicate that no characters were converted if s points to NULL.

7. If the wide-character value is equal to or less than 0x9f, moves that value into the first byte of the s array and returns 1 to indicate that the converted character is 1 byte in length.

8. If the wide-character value is in the range 0x0100 to 0x015d, moves the value 0x8e to the first byte and a calculated value to the second byte of the s array; returns 2 to indicate that the converted character is 2 bytes in length.

9. If the wide-character value is in the range 0x015e to 0x303b, moves calculated values to the first and second bytes of the s array and returns 2 to indicate that the converted character is 2 bytes in length.

10. If the wide-character value is in the range 0x303c to 0x5f19, moves 0x8f to the first byte and calculated values to the second and third bytes of the s array; returns 3 to indicate that the converted character is 3 bytes in length.

11. If the wide-character value is in the range 0x5f1a to 0x8df7, moves calculated values to the first and second bytes of the s array, and returns 2 to indicate that the converted character is 2 bytes in length.

12. Sets errno to EILSEQ and returns -1 to indicate that the wide-character value is invalid.

    These statements execute if the wide-character values satisfies none of the preceding conditions.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/localedef.h>   

/*
The algorithm for this conversion is:

PC <= 0x009f:                 s[0] = PC
PC >= 0x0100 and PC <=0x015d: s[0] = 0x8e
                              s[1] = PC - 0x005f
PC >= 0x015e and PC <=0x303b: s[0] = ((PC - 0x015e) >> 7) + 0x00a1
                              s[1] = ((PC - 0x015e) & 0x007f) + 0x00a1
PC >= 0x303c and PC <=0x5f19: s[0] = 0x8f
                              s[1] = ((PC - 0x303c) >> 7) + 0x00a1
                              s[2] = ((PC - 0x303c) & 0x007f) + 0x00a1
PC >= 0x5f1a and PC <=0x8df7  s[0] = ((PC - 0x5f1a) >> 7) + 0x00a1
                              s[1] = ((PC - 0x5f1a) & 0x007f) + 0x0021

+-----------------+-----------+-----------+-----------+
|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)

int __wcswidth_sdeckanji(
        const wchar_t *wcs,   (3)
        size_t n,   (4)
        _LC_charmap_t *hdl )   (5)
{
    int len;   (6)
    int i;   (7)

    if (wcs == (wchar_t *)NULL || *wcs == (wchar_t)NULL)
        return(0);   (8)

    len = 0;   (9)
    for (i=0; wcs[i] != (wchar_t)NULL && i<n; i++) {   (10)

        if (wcs[i] <= 0x9f)
             len += 1;   (11)

        else if ((wcs[i] >= 0x0100) && (wcs[i] <= 0x015d))
             len += 1;   (12)

        else if ((wcs[i] >=0x015e) && (wcs[i] <= 0x303b))
             len += 2;   (13)

        else if ((wcs[i] >=0x303c) && (wcs[i] <= 0x5f19))
            len += 2;   (14)

        else if ((wcs[i] >=0x5f1a) && (wcs[i] <= 0x8df7))
            len += 2;   (15)

        else
            return(-1);   (16)
    }   (17)

    return(len);   (18)
}

1. Include header files that contain constants and structures required for this method.

2. Describes the algorithm used to determine the required display width.

   Note that each character's display width is either 1 or 2 columns, depending on the character set to which a character belongs. Display width is different from the size of the character in multibyte format; for example, triple-byte characters require 2 display columns and double-byte characters can require either 1 or 2 display columns.

3. Points, through wcs, to a buffer that stores the wide-character string for which display width information is requested.

4. Defines a variable, n, that stores the maximum size of the wcs buffer.

5. Points, through hdl, to a structure that stores pointers to the methods that parse character maps for this locale.

6. Defines a variable, len, that stores the display width in bytes/columns.

7. Defines a variable, i, that functions as a loop counter.

8. Returns zero (0) if wcs contains or points to NULL.

9. Initializes len to zero (0).

10. Begins a for loop that processes each wide character in the wcs buffer and increments the wide-character pointer.

11. Increments len by 1 if the value of the current wide character is less than or equal to 0x9f.

12. Increments len by 1 if the value of the current wide character is in the range 0x0100 to 0x015d.

13. Increments len by 2 if the value of the current wide character is in the range 0x015e to 0x303b.

14. Increments len by 2 if the value of the current wide character is in the range 0x303c to 0x5f19.

15. Increments len by 2 if the value of the current wide character is in the range 0x5f1a to 0x8df7.

16. Returns -1 to indicate that the string contains an invalid wide character.

    This statement executes if a value that satisfies none of the preceding conditions is encountered in the string. The calling function, wcswidth(), also returns -1 if the wide character is nonprintable; however, this condition is evaluated at the level of the calling function and does not need to be evaluated by the method.

17. Ends the for loop that processes wide characters in the wcs buffer.

18. Returns len to indicate the number of columns required to display the wide-character string.

#include <stdlib.h>   (1)
#include <wchar.h>   
#include <sys/localedef.h>   

/*
The algorithm for this conversion is:

PC <= 0x009f:                 s[0] = PC
PC >= 0x0100 and PC <=0x015d: s[0] = 0x8e
                              s[1] = PC - 0x005f
PC >= 0x015e and PC <=0x303b: s[0] = ((PC - 0x015e) >> 7) + 0x00a1
                              s[1] = ((PC - 0x015e) & 0x007f) + 0x00a1
PC >= 0x303c and PC <=0x5f19: s[0] = 0x8f
                              s[1] = ((PC - 0x303c) >> 7) + 0x00a1
                              s[2] = ((PC - 0x303c) & 0x007f) + 0x00a1
PC >= 0x5f1a and PC <=0x8df7  s[0] = ((PC - 0x5f1a) >> 7) + 0x00a1
                              s[1] = ((PC - 0x5f1a) & 0x007f) + 0x0021

+-----------------+-----------+-----------+-----------+
|  process code   |   s[0]    |   s[1]    |   s[2]    |
+-----------------+-----------+-----------+-----------+
| 0x0000 - 0x009f | 0x00-0x9f |    --     |    --     |
| 0x00a0 - 0x00ff |   --      |    --     |    --     |
| 0x0100 - 0x015d | 0x8e      | 0xa1-0xfe |    --     | JIS X0201 RH
| 0x015e - 0x303b | 0xa1-0xfe | 0xa1-0xfe |    --     | JIS X0208
| 0x303c - 0x5f19 | 0x8f      | 0xa1-0xfe | 0xa1-0xfe | JIS X0212
| 0x5f1a - 0x8df7 | 0xa1-0xfe | 0x21-0xfe |    --     | UDC
+-----------------+-----------+-----------+-----------+
*/   (2)

int __wcwidth_sdeckanji(
        wint_t wc,   (3)
        _LC_charmap_t *hdl )   (4)
{

    if (wc == 0)
        return(0);   (5)

    if (wc <= 0x9f)
        return(1);   (6)

    else if ((wc >= 0x0100) && (wc <= 0x015d))
        return(1);   (7)

    else if ((wc >=0x015e) && (wc <= 0x303b))
        return(2);   (8)

    else if ((wc >=0x303c) && (wc <= 0x5f19))
        return(2);   (9)

    else if ((wc >=0x5f1a) && (wc <= 0x8df7))
        return(2);   (10)
        return(-1);   (11)
}

1. Include header files that contain constants and structures required for this method.

2. Describes the algorithm used to determine the required display width.

   Note that a character's display width is either 1 or 2 columns, depending on the character set to which a character belongs. Display width is different from the size of the character in multibyte format; for example, triple-byte characters require 2 display columns and double-byte characters can require either 1 or 2 display columns.

3. Defines the wc variable that stores the wide character for which display width information is requested.

4. Points, through hdl, to a structure that stores pointers to the methods that parse character maps for this locale.

5. Returns zero (0) if the wide-character buffer is empty.

6. Returns 1 if the wide-character value is less than or equal to 0x009f.

7. Returns 1 if the wide-character value is in the range 0x0100 to 0x015d.

8. Returns 2 if the wide-character value is in the range 0x015e to 0x303b.

9. Returns 2 if the wide-character value is in the range 0x303c to 0x5f19.

10. Returns 2 if the wide-character value is in the range 0x5f1a to 0x8df7.

11. Returns -1 if the wide-character value is invalid.

    The calling function, wcwidth(), also returns -1 if the wide character is nonprintable; however, this condition is evaluated at the level of the calling function and does not need to be evaluated by the method.

cc -std0 -c \
   __mblen_sdeckanji.c __mbstopcs_sdeckanji.c \
   __mbstowcs_sdeckanji.c __mbtopc_sdeckanji.c \
   __mbtowc_sdeckanji.c __pcstombs_sdeckanji.c \
   __pctomb_sdeckanji.c __wcstombs_sdeckanji.c \
   __wcswidth_sdeckanji.c __wctomb_sdeckanji.c \
   __wcwidth_sdeckanji.c

ld -shared -set_version osf.1 -soname libsdeckanji.so -shared \
   -no_archive -o libsdeckanji.so \
   __mblen_sdeckanji.o __mbstopcs_sdeckanji.o \
   __mbstowcs_sdeckanji.o __mbtopc_sdeckanji.o \
   __mbtowc_sdeckanji.o __pcstombs_sdeckanji.o __pctomb_sdeckanji.o \
   __wcstombs_sdeckanji.o __wcswidth_sdeckanji.o __wctomb_sdeckanji.o \
   __wcwidth_sdeckanji.o \
   -lc

% localedef -f ISO8859-1.cmap \    (1)
-i de_DE.ISO8859-1.lscr \   (2)
de_DE.ISO8859-1@example   (3)

% setenv LOCPATH ~harry/locales

% setenv LANG de_DE.ISO8859-1@example

% date
12.Dezember 1993 09:18:11

Note

The LOCPATH variable is an extension to specifications in the X/Open UNIX standard and therefore may not be recognized on all systems that conform to this standard.

Some programs have support files that are installed in system directories with names that exactly match the names of standard locales. In such cases, application software, system software, or both might use the value of the LANG environment variable to determine the locale-specific directory in which the support files reside. If assigned directly to the LANG or LC_ALL environment variable, locale file names with an at (@) suffix may result in invalid search paths for some applications. The following example shows how you can work around this problem by assigning the standard locale name to the LANG variable and the name of your variant locale to the locale category variables. You need to make assignments only to those category variables that represent areas where your locale differs from the locale on which it is based.

% setenv LANG de_DE.ISO8859-1

% setenv LC_CTYPE de_DE.ISO8859-1@example

% setenv LC_COLLATE de_DE.ISO8859-1@example

.
.
.


% setenv LC_TIME de_DE.ISO8859-1@example