4.4BSD/usr/share/man/cat3/rune.0

RUNE(3)                     BSD Programmer's Manual                    RUNE(3)

NNAAMMEE
     sseettrruunneellooccaallee, sseettiinnvvaalliiddrruunnee, ssggeettrruunnee, ssppuuttrruunnee - rune support for C

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<rruunnee..hh>>
     ##iinncclluuddee <<eerrrrnnoo..hh>>

     _i_n_t
     sseettrruunneellooccaallee(_c_h_a_r _*_l_o_c_a_l_e);

     _v_o_i_d
     sseettiinnvvaalliiddrruunnee(_r_u_n_e___t _r_u_n_e);

     _r_u_n_e___t
     ssggeettrruunnee(_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g, _s_i_z_e___t _n, _c_h_a_r _c_o_n_s_t _*_*_r_e_s_u_l_t);

     _i_n_t
     ssppuuttrruunnee(_r_u_n_e___t _r_u_n_e, _c_h_a_r _*_s_t_r_i_n_g, _s_i_z_e___t _n, _c_h_a_r _*_*_r_e_s_u_l_t);


     ##iinncclluuddee <<ssttddiioo..hh>>

     _l_o_n_g
     ffggeettrruunnee(_F_I_L_E _*_s_t_r_e_a_m);

     _i_n_t
     ffuunnggeettrruunnee(_r_u_n_e___t _r_u_n_e, _F_I_L_E _*_s_t_r_e_a_m);

     _i_n_t
     ffppuuttrruunnee(_r_u_n_e___t _r_u_n_e, _F_I_L_E _*_s_t_r_e_a_m);

DDEESSCCRRIIPPTTIIOONN
     The sseettrruunneellooccaallee() controls the type of encoding used to represent runes
     as multibyte strings as well as the properties of the runes as defined in
     <<ccttyyppee..hh>>.  The _l_o_c_a_l_e argument indicates the locale which to load.  If
     the locale is successfully loaded, 0 is returned, otherwise an errno val-
     ue is returned to indicate the type of error.

     The sseettiinnvvaalliiddrruunnee() function sets the value of the global value
     _INVALID_RUNE to be _r_u_n_e_.

     The ssggeettrruunnee() function tries to read a single multibyte character from
     _s_t_r_i_n_g, which is at most _n bytes long.  If ssggeettrruunnee() is successful, the
     rune is returned.  If _r_e_s_u_l_t is not NULL, _*_r_e_s_u_l_t will point to the first
     byte which was not converted in _s_t_r_i_n_g_. If the first _n bytes of _s_t_r_i_n_g do
     not describe a full multibyte character, _INVALID_RUNE is returned and
     _*_r_e_s_u_l_t will point to _s_t_r_i_n_g_. If there is an encoding error at the start
     of _s_t_r_i_n_g, _INVALID_RUNE is returned and _*_r_e_s_u_l_t will point to the second
     character of _s_t_r_i_n_g_.

     the ssppuuttrruunnee() function tries to encode _r_u_n_e as a multibyte string and
     store it at _s_t_r_i_n_g, but no more than _n bytes will be stored.  If _r_e_s_u_l_t
     is not NULL, _*_r_e_s_u_l_t will be set to point to the first byte in string
     following the new multibyte character.  If _s_t_r_i_n_g is NULL, _*_r_e_s_u_l_t will
     point to (char *)0 + _x, where _x is the number of bytes that would be
     needed to store the multibyte value.  If the multibyte character would
     consist of more than _n bytes and _r_e_s_u_l_t is not NULL, _*_r_e_s_u_l_t will be set
     to NULL. In all cases, ssppuuttrruunnee() will return the number of bytes which
     would be needed to store _r_u_n_e as a multibyte character.

     The ffggeettrruunnee() function operates the same as ssggeettrruunnee() with the excep-
     tion that it attempts to read enough bytes from _s_t_r_e_a_m to decode a single
     rune.  It returns either EOF on end of file, _INVALID_RUNE on an encoding
     error, or the rune decoded if all went well.

     The ffuunnggeettrruunnee() function function pushes the multibyte encoding, as pro-
     vided by ssppuuttrruunnee(), of _r_u_n_e onto _s_t_r_e_a_m such that the next ffggeettrruunnee()
     call will return _r_u_n_e. It returns EOF if it fails and 0 on success.

     The ffppuuttrruunnee() function writes the multibyte encoding of _r_u_n_e, as provid-
     ed by ssppuuttrruunnee(), onto _s_t_r_e_a_m. It returns EOF on failure and 0 on suc-
     cess.

RREETTUURRNN VVAALLUUEESS
     The sseettrruunneellooccaallee() function returns one of the following values:

     0         _s_e_t_r_u_n_e_l_o_c_a_l_e _w_a_s _s_u_c_c_e_s_s_f_u_l_.

     EFAULT    _l_o_c_a_l_e was NULL.

     ENOENT    The locale could not be found.

     EFTYPE    The file found was not a valid file.

     EINVAL    The encoding indicated by the locale was unknown.

     The ssggeettrruunnee() function either returns the rune read or _INVALID_RUNE.
     The ssppuuttrruunnee() function returns the number of bytes needed to store _r_u_n_e
     as a multibyte string.

FFIILLEESS
     $PATH_LOCALE/_l_o_c_a_l_e/LC_CTYPE
     /usr/share/locale/_l_o_c_a_l_e/LC_CTYPE  binary LC_CTYPE file for the locale
                                        _l_o_c_a_l_e.

SSEEEE AALLSSOO
     euc(4),  mbrune(3),  setlocale(3),  utf2(4)

NNOOTTEE
     The ANSI C type wchar_t is the same as rune_t. Rune_t was chosen to ac-
     cent the purposeful choice of not basing the system with the ANSI C prim-
     itives, which were, shall we say, less aesthetic.

HHIISSTTOORRYY
     These functions first appeared in 4.4BSD.

     The sseettrruunneellooccaallee() function and the other non-ANSI rune functions were
     inspired by PPllaann 99 ffrroomm BBeellll LLaabbss as a much more sane alternative to the
     ANSI multibyte and wide character support.

     All of the ANSI multibyte and wide character support functions are built
     using the rune functions.

4.4BSD                           June 27, 1993                               2