Libc-1082.20.4.tar.gz

[apple/libc.git] / locale / FreeBSD / mbsrtowcs.3

diff --git a/locale/FreeBSD/mbsrtowcs.3 b/locale/FreeBSD/mbsrtowcs.3
index 661366a51a075d525cfbb1c0bce79881fa05ec45..ff6e6990825eac55a10c8ee621852224a1cf7ad9 100644 (file)
--- a/locale/FreeBSD/mbsrtowcs.3
+++ b/locale/FreeBSD/mbsrtowcs.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2002 Tim J. Robbins
+.\" Copyright (c) 2002-2004 Tim J. Robbins

 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without


@@ -22,28 +22,60 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"

-.\" $FreeBSD: src/lib/libc/locale/mbsrtowcs.3,v 1.3 2002/11/29 17:35:09 ru Exp $
-.Dd August 16, 2002
+.\" $FreeBSD: src/lib/libc/locale/mbsrtowcs.3,v 1.6 2005/01/11 20:50:49 ru Exp $
+.Dd July 21, 2004

 .Dt MBSRTOWCS 3
 .Os
 .Sh NAME
 .Dt MBSRTOWCS 3
 .Os
 .Sh NAME

-.Nm mbsrtowcs
+.Nm mbsnrtowcs ,
+.Nm mbsnrtowcs_l ,
+.Nm mbsrtowcs ,
+.Nm mbsrtowcs_l

 .Nd "convert a character string to a wide-character string (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In wchar.h
 .Ft size_t
 .Nd "convert a character string to a wide-character string (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In wchar.h
 .Ft size_t

+.Fo mbsnrtowcs
+.Fa "wchar_t *restrict dst"
+.Fa "const char **restrict src"
+.Fa "size_t nms"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.Ft size_t

 .Fo mbsrtowcs
 .Fo mbsrtowcs

-.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len"
-.Fa "mbstate_t * restrict ps"
+.Fa "wchar_t *restrict dst"
+.Fa "const char **restrict src"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.In wchar.h
+.In xlocale.h
+.Ft size_t
+.Fo mbsrtowcs_l
+.Fa "wchar_t *restrict dst"
+.Fa "const char **restrict src"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"
+.Fc
+.Ft size_t
+.Fo mbsnrtowcs_l
+.Fa "wchar_t *restrict dst"
+.Fa "const char **restrict src"
+.Fa "size_t nms"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"

 .Fc
 .Sh DESCRIPTION
 The
 .Fn mbsrtowcs
 .Fc
 .Sh DESCRIPTION
 The
 .Fn mbsrtowcs

-function converts a sequence of multibyte characters pointed to indirectly by
-.Fa src
-into a sequence of corresponding wide characters and stores at most
+function converts a sequence of multibyte characters, pointed to indirectly by
+.Fa src ,
+into a sequence of corresponding wide characters. It stores at most

 .Fa len
 of them in the
 .Vt wchar_t
 .Fa len
 of them in the
 .Vt wchar_t


@@ -80,11 +112,35 @@ If it is
 .Fn mbsrtowcs
 uses an internal, static
 .Vt mbstate_t
 .Fn mbsrtowcs
 uses an internal, static
 .Vt mbstate_t

-object.
+object, which is initialized to the initial conversion state
+at program startup.
+.Pp
+The
+.Fn mbsnrtowcs
+function behaves identically to
+.Fn mbsrtowcs ,
+except that conversion stops after reading at most
+.Fa nms
+bytes from the buffer pointed to by
+.Fa src .
+.Pp
+While the
+.Fn mbsrtowcs
+and
+.Fn mbsnrtowcs
+functions use the current locale, the
+.Fn mbsrtowcs_l
+and
+.Fn mbsnrtowcs_l
+functions may be passed locales directly. See
+.Xr xlocale 3
+for more information.

 .Sh RETURN VALUES
 The
 .Fn mbsrtowcs
 .Sh RETURN VALUES
 The
 .Fn mbsrtowcs

-function returns the number of wide characters stored in
+and
+.Fn mbsnrtowcs
+functions return the number of wide characters stored in

 the array pointed to by
 .Fa dst
 if successful, otherwise it returns
 the array pointed to by
 .Fa dst
 if successful, otherwise it returns


@@ -92,19 +148,27 @@ if successful, otherwise it returns
 .Sh ERRORS
 The
 .Fn mbsrtowcs
 .Sh ERRORS
 The
 .Fn mbsrtowcs

-function will fail if:
+and
+.Fn mbsnrtowcs
+functions will fail if:

 .Bl -tag -width Er
 .It Bq Er EILSEQ
 An invalid multibyte character sequence was encountered.
 .Bl -tag -width Er
 .It Bq Er EILSEQ
 An invalid multibyte character sequence was encountered.

+.It Bq Er EINVAL
+The conversion state is invalid.

 .El
 .Sh SEE ALSO
 .Xr mbrtowc 3 ,
 .Xr mbstowcs 3 ,
 .El
 .Sh SEE ALSO
 .Xr mbrtowc 3 ,
 .Xr mbstowcs 3 ,

-.Xr wcsrtombs 3
+.Xr multibyte 3 ,
+.Xr wcsrtombs 3 ,
+.Xr xlocale 3

 .Sh STANDARDS
 The
 .Fn mbsrtowcs
 function conforms to
 .St -isoC-99 .
 .Sh STANDARDS
 The
 .Fn mbsrtowcs
 function conforms to
 .St -isoC-99 .

-.Sh BUGS
-The current implementation does not support shift states.
+.Pp
+The
+.Fn mbsnrtowcs
+function is an extension to the standard.