RUNE(3) BSD Library Functions Manual RUNE(3)NAME
setrunelocale, setinvalidrune, sgetrune, sputrune — rune support for C
sgetrune(const char *string, size_t n, char const **result);
sputrune(rune_t rune, char *string, size_t n, char **result);
fungetrune(rune_t rune, FILE *stream);
fputrune(rune_t rune, FILE *stream);
The setrunelocale() controls the type of encoding used to represent runes
as multibyte strings as well as the properties of the runes as defined in
<ctype.h>. 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 setinvalidrune() function sets the value of the global value
_INVALID_RUNE to be rune.
The sgetrune() function tries to read a single multibyte character from
string, which is at most n bytes long. If sgetrune() 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, _INVALID_RUNE is returned and
*result will point to string. If there is an encoding error at the start
of string, _INVALID_RUNE is returned and *result will point to the second
character of string.
the sputrune() 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, sputrune() will return the number of bytes which
would be needed to store rune as a multibyte character.
The fgetrune() function operates the same as sgetrune() 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, _INVALID_RUNE on an encoding
error, or the rune decoded if all went well.
The fungetrune() function pushes the multibyte encoding, as provided by
sputrune(), of rune onto stream such that the next fgetrune() call will
return rune. It returns EOF if it fails and 0 on success.
The fputrune() function writes the multibyte encoding of rune, as pro‐
vided by sputrune(), onto stream. It returns EOF on failure and 0 on
The setrunelocale() function returns one of the following values:
0 setrunelocale was successful.
EFAULT locale 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 sgetrune() function either returns the rune read or _INVALID_RUNE.
The sputrune() function returns the number of bytes needed to store rune
as a multibyte string.
/usr/share/locale/locale/LC_CTYPE binary LC_CTYPE file for the locale
SEE ALSOeuc(4), mbrune(3), setlocale(3), utf2(4)NOTE
The ANSI C type wchar_t is the same as rune_t. Rune_t was chosen to
accent the purposeful choice of not basing the system with the ANSI C
primitives, which were, shall we say, less aesthetic.
These functions first appeared in 4.4BSD.
The setrunelocale() function and the other non-ANSI rune functions were
inspired by Plan 9 from Bell Labs 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.
BSD September 24, 2021 BSD