arm_is_charset_supported(3)

1arm_is_charset_supported(3)ARM 4 Programmer's Manualarm_is_charset_supported(3)
2
3
4

NAME

6       arm_is_charset_supported - check character encoding
7

SYNOPSIS

9       #include <arm4.h>
10
11       arm_error_t
12       arm_is_charset_supported(
13           const arm_charset_t charset,
14           arm_boolean_t *supported);
15

DESCRIPTION

17       arm_is_charset_supported()  indicates whether an ARM library supports a
18       specified character encoding.
19
20       The default encoding for all strings provided by the application on all
21       operating  systems  is  UTF-8.  An application may specify an alternate
22       encoding when executing arm_register_application(), and then use it for
23       all  strings  it  provides on all calls including arm_register_applica‐
24       tion(),   but   should   never   do   so    without    first    issuing
25       arm_is_charset_supported() to test whether the value is supported.
26
27       An  ARM library on the operating systems listed in Table 1 must support
28       the specified encodings. Applications are  encouraged  to  use  one  of
29       these  encodings to ensure that any ARM implementation will support the
30       application's ARM instrumentation. Another alternative is to use one of
31       these  encodings  along  with  a preferred encoding. If the ARM library
32       supports the preferred encoding, it is  used;  otherwise,  one  of  the
33       mandatory encodings is used.
34
35       Table 1: Mandatory Encodings by Platform
36
37       ┌────────────────────┬─────────────┬┬─────────────────┬───────────┬────────┬──────┐
38       │   IANA MIBenum     │  Character  ││      UNIX       │ Microsoft │  IBM   │ IBM  │
39       │                    │     Set     ││      and        │  Windows  │ OS/400 │ zOS  │
40       │                    │ Common Name ││     Linux       │           │        │      │
41       ├────────────────────┼─────────────┼┼─────────────────┼───────────┼────────┼──────┤
42       │         3          │   ASCII-7   ││      Yes        │    Yes    │  Yes   │ Yes  │
43       │ ARM_CHARSET_ASCII  │             ││   (US-ASCII)    │           │        │      │
44       ├────────────────────┼─────────────┼┼─────────────────┼───────────┼────────┼──────┤
45       │        106         │    UTF-8    ││      Yes        │    Yes    │  Yes   │ Yes  │
46       │ ARM_CHARSET_UTF8   │             ││     (UCS-2      │           │        │      │
47       │                    │             ││characters only) │           │        │      │
48       ├────────────────────┼─────────────┼┼─────────────────┼───────────┼────────┼──────┤
49       │       1014         │   UTF-16    ││                 │    Yes    │        │      │
50       │ARM_CHARSET_UTF16LE │             ││ Little Endian   │           │        │      │
51       │                    │             ││     (UCS-2      │           │        │      │
52       │                    │             ││characters only) │           │        │      │
53       ├────────────────────┼─────────────┼┼─────────────────┼───────────┼────────┼──────┤
54       │       2028         │   IBM037    ││                 │           │ Yes    │      │
55       │ARM_CHARSET_IBM037  │             ││                 │           │        │      │
56       ├────────────────────┼─────────────┼┼─────────────────┼───────────┼────────┼──────┤
57       │       2102         │   IBM1047   ││                 │           │        │ Yes  │
58       │ARM_CHARSET_IBM1047 │             ││                 │           │        │      │
59       └────────────────────┴─────────────┴┴─────────────────┴───────────┴────────┴──────┘
60       charset   is  an  IANA  (Internet  Assigned  Numbers  Authority  -  see
61       www.iana.org) MIBenum value. Support for some values  is  mandatory  by
62       any ARM implementation on a specified platform, as shown in the table.
63
64       supported  is a pointer to a boolean value that is set to true or false
65       to indicate whether charset is a supported encoding.
66

RETURN VALUE

68       On success, the function returns ARM_SUCCESS. A  non-zero  value  indi‐
69       cates an error.
70

ERRORS

72       If  the  return code is negative, an error occurred. If the return code
73       is not negative, an error may or may not have occurred - the determina‐
74       tion  of  what  is an error and whether an error code is returned is at
75       the discretion of the ARM implementation. The application can test  the
76       return code if it wants to provide its own error logging.
77
78       The following errors are recognized by this implementation, but may not
79       be portable to other implementations:
80
81
82       ARM_FAILURE_NULL_ARGUMENT
83              The supported pointer must not be null.
84

CONFORMING TO

86       ARM Issue 4.0 C Language Bindings, Version 2
87

EXAMPLE

89       None.
90