Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RUNE(3)			 BSD Library Functions Manual		       RUNE(3)

     setrunelocale, setinvalidrune, sgetrune, sputrune,	fgetrune, fungetrune,
     fputrune -- rune support for C

     Standard C	Library	(libc, -lc)

     #include <rune.h>
     #include <errno.h>

     setrunelocale(char	*locale);

     setinvalidrune(rune_t rune);

     sgetrune(const char *string, size_t n, char const **result);

     sputrune(rune_t rune, char	*string, size_t	n, char	**result);

     #include <stdio.h>

     fgetrune(FILE *stream);

     fungetrune(rune_t rune, FILE *stream);

     fputrune(rune_t rune, FILE	*stream);

     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 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			The setrunelocale() 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 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

     mbrune(3),	setlocale(3), euc(5), utf2(5), utf8(5)

     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.

BSD				October	6, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help