RUNE(3) BSD Programmer's Manual RUNE(3)NAME
setrunelocale, setinvalidrune, sgetrune, sputrune - rune support for C
SYNOPSIS
#include <rune.h>
#include <errno.h>
int
setrunelocale(char *locale);
void
setinvalidrune(rune_t rune);
rune_t
sgetrune(const char *string, size_t n, char const **result);
int
sputrune(rune_t rune, char *string, size_t n, char **result);
#include <stdio.h>
long
fgetrune(FILE *stream);
int
fungetrune(rune_t rune, FILE *stream);
int
fputrune(rune_t rune, FILE *stream);
DESCRIPTION
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 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 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 function pushes the multibyte encoding, as pro-
vided 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 provid-
ed by sputrune(), onto stream. It returns EOF on failure and 0 on suc-
cess.
RETURN VALUES
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.
FILES
$PATH_LOCALE/locale/LC_CTYPE
/usr/share/locale/locale/LC_CTYPE binary LC_CTYPE file for the locale
locale.
SEE ALSOeuc(4), mbrune(3), setlocale(3), utf8(4)NOTE
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.
HISTORY
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.
BSDI BSD/OS June 27, 1993 2
