RUNE(3) BSD Library Functions Manual RUNE(3)

NAME
     sseettrruunneellooccaallee, sseettiinnvvaalliiddrruunnee, ssggeettrruunnee, ssppuuttrruunnee, ffggeettrruunnee, ffuunnggeettrruunnee,
     ffppuuttrruunnee - rune support for C

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>
     ##iinncclluuddee <>

     int
     sseettrruunneellooccaallee(char *locale);

     void
     sseettiinnvvaalliiddrruunnee(runet rune);

     runet
     ssggeettrruunnee(const char *string, sizet n, char const **result);

     int
     ssppuuttrruunnee(runet rune, char *string, sizet n, char **result);

     ##iinncclluuddee <>

     long
     ffggeettrruunnee(FILE *stream);

     int
     ffuunnggeettrruunnee(runet rune, FILE *stream);

     int
     ffppuuttrruunnee(runet rune, FILE *stream);

DESCRIPTION
     The 4.4BSD ``rune'' functions have been deprecated in favour of the ISO
     C99 extended multibyte and wide character facilities and should not be
     used in new applications.  Consider using setlocale(3), mbrtowc(3),
     wcrtomb(3), fgetwc(3), ungetwc(3), and fputwc(3) instead.

     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
     .  The locale argument indicates which locale to load.  If the
     locale is successfully loaded, 0 is returned, otherwise an errno value is
     returned to indicate the type of error.

     The sseettiinnvvaalliiddrruunnee() function sets the value of the global value
     INVALIDRUNE to be rune.

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

     the ssppuuttrruunnee() function tries to encode rune as a multibyte string and
     store it at string, but no more than n bytes will be stored.  If result
     is not NULL, *result will be set to point to the first byte in string
     following the new multibyte character.  If string is NULL, *result 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 result is not NULL, *result will be set
     to NULL.  In all cases, ssppuuttrruunnee() will return the number of bytes which
     would be needed to store rune as a multibyte character.

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

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

     The ffppuuttrruunnee() function writes the multibyte encoding of rune, as pro-
     vided by ssppuuttrruunnee(), onto stream.  It returns EOF on failure and 0 on
     success.

RETURN VALUES
     The sseettrruunneellooccaallee() function returns one of the following values:

     0                  The sseettrruunneellooccaallee() function was successful.

     [EINVAL]           The locale name was incorrect.

     [ENOENT]           The locale could not be found.

     [EFTYPE]           The file found was not a valid file.

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

FILES
     $PATHLOCALE/locale/LCCTYPE
     /usr/share/locale/locale/LCCTYPE  binary LCCTYPE file for the locale
                                        locale.

SEE ALSO
     mbrune(3), setlocale(3), euc(4), utf2(4), utf8(5)

HISTORY     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.

BSD                             October 6, 2002                            BSD