Libc-1082.50.1.tar.gz

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

diff --git a/locale/FreeBSD/wcsrtombs.3 b/locale/FreeBSD/wcsrtombs.3
index eb77a5d6b8a420746ce7211fcf95a1a8e06301f5..0848655cfae3966ef8beed0480d922c212a96792 100644 (file)
--- a/locale/FreeBSD/wcsrtombs.3
+++ b/locale/FreeBSD/wcsrtombs.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
@@ -22,30 +22,63 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/lib/libc/locale/wcsrtombs.3,v 1.3 2002/11/29 17:35:09 ru Exp $
+.\" $FreeBSD: src/lib/libc/locale/wcsrtombs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $
 .\"
-.Dd August 16, 2002
+.Dd July 21, 2004
 .Dt WCSRTOMBS 3
 .Os
 .Sh NAME
-.Nm wcsrtombs
+.Nm wcsnrtombs ,
+.Nm wcsnrtombs_l ,
+.Nm wcsrtombs ,
+.Nm wcsrtombs_l
 .Nd "convert a wide-character string to a character string (restartable)"
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In wchar.h
 .Ft size_t
+.Fo wcsnrtombs
+.Fa "char *restrict dst"
+.Fa "const wchar_t **restrict src"
+.Fa "size_t nwc"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.Ft size_t
 .Fo wcsrtombs
-.Fa "char * restrict dst" "const wchar_t ** restrict src"
-.Fa "size_t len" "mbstate_t * restrict ps"
+.Fa "char *restrict dst"
+.Fa "const wchar_t **restrict src"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fc
+.In wchar.h
+.In xlocale.h
+.Ft size_t
+.Fo wcsnrtombs_l
+.Fa "char *restrict dst"
+.Fa "const wchar_t **restrict src"
+.Fa "size_t nwc"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"
+.Fc
+.Ft size_t
+.Fo wcsrtombs_l
+.Fa "char *restrict dst"
+.Fa "const wchar_t **restrict src"
+.Fa "size_t len"
+.Fa "mbstate_t *restrict ps"
+.Fa "locale_t loc"
 .Fc
 .Sh DESCRIPTION
 The
 .Fn wcsrtombs
-function converts a string of wide characters indirectly pointed to by
-.Fa src
-to a corresponding multibyte character string stored in the array
-pointed to by
+function converts a string of wide characters,
+indirectly pointed to by
+.Fa src ,
+to a corresponding multi-byte character string,
+stored in the array pointed to by
 .Fa dst .
 No more than
 .Fa len
@@ -80,31 +113,63 @@ If it is
 .Fn wcsrtombs
 uses an internal, static
 .Vt mbstate_t
-object.
-.Sh RETURN VALUES
+object, which is initialized to the initial conversion state
+at program startup.
+.Pp
 The
+.Fn wcsnrtombs
+function behaves identically to
+.Fn wcsrtombs ,
+except that conversion stops after reading at most
+.Fa nwc
+characters from the buffer pointed to by
+.Fa src .
+.Pp
+Although the
 .Fn wcsrtombs
-function returns the number of bytes stored in
+and
+.Fn wcsnrtombs
+functions use the current locale, the
+.Fn wcsrtombs_l
+and
+.Fn wcsnrtombs_l
+functions may be passed locales directly. See
+.Xr xlocale 3
+for more information.
+.Sh RETURN VALUES
+If successful, the
+.Fn wcsrtombs
+and
+.Fn wcsnrtombs
+functions return the number of bytes stored in
 the array pointed to by
 .Fa dst
-(not including any terminating null), if successful, otherwise it returns
+(not including any terminating null);
+otherwise, they return
 .Po Vt size_t Pc Ns \-1 .
 .Sh ERRORS
 The
 .Fn wcsrtombs
-function will fail if:
+and
+.Fn wcsnrtombs
+functions will fail if:
 .Bl -tag -width Er
 .It Bq Er EILSEQ
 An invalid wide character was encountered.
+.It Bq Er EINVAL
+The conversion state is invalid.
 .El
 .Sh SEE ALSO
 .Xr mbsrtowcs 3 ,
 .Xr wcrtomb 3 ,
-.Xr wcstombs 3
+.Xr wcstombs 3 ,
+.Xr xlocale 3
 .Sh STANDARDS
 The
 .Fn wcsrtombs
 function conforms to
 .St -isoC-99 .
-.Sh BUGS
-The current implementation does not support shift states.
+.Pp
+The
+.Fn wcsnrtombs
+function is an extension to the standard.