mbsrtowcs.3p (6053B)
- '\" et
- .TH MBSRTOWCS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- mbsnrtowcs, mbsrtowcs
- \(em convert a character string to a wide-character string (restartable)
- .SH SYNOPSIS
- .LP
- .nf
- #include <wchar.h>
- .P
- size_t mbsnrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP,
- size_t \fInmc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
- size_t mbsrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP,
- size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
- .fi
- .SH DESCRIPTION
- For
- \fImbsrtowcs\fR():
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- The
- \fImbsrtowcs\fR()
- function shall convert a sequence of characters, beginning in the
- conversion state described by the object pointed to by
- .IR ps ,
- from the array indirectly pointed to by
- .IR src
- into a sequence of corresponding wide characters. If
- .IR dst
- is not a null pointer, the converted characters shall be stored into
- the array pointed to by
- .IR dst .
- Conversion continues up to and including a terminating null character,
- which shall also be stored. Conversion shall stop early in either of
- the following cases:
- .IP " *" 4
- A sequence of bytes is encountered that does not form a valid character.
- .IP " *" 4
- .IR len
- codes have been stored into the array pointed to by
- .IR dst
- (and
- .IR dst
- is not a null pointer).
- .P
- Each conversion shall take place as if by a call to the
- \fImbrtowc\fR()
- function.
- .P
- If
- .IR dst
- is not a null pointer, the pointer object pointed to by
- .IR src
- shall be assigned either a null pointer (if conversion stopped due to
- reaching a terminating null character) or the address just past the
- last character converted (if any). If conversion stopped due to
- reaching a terminating null character, and if
- .IR dst
- is not a null pointer, the resulting state described shall be the
- initial conversion state.
- .P
- If
- .IR ps
- is a null pointer, the
- \fImbsrtowcs\fR()
- function shall use its own internal
- .BR mbstate_t
- object, which is initialized at program start-up to the initial
- conversion state. Otherwise, the
- .BR mbstate_t
- object pointed to by
- .IR ps
- shall be used to completely describe the current conversion state of
- the associated character sequence.
- .P
- The
- \fImbsnrtowcs\fR()
- function shall be equivalent to the
- \fImbsrtowcs\fR()
- function, except that the conversion of characters indirectly
- pointed to by
- .IR src
- is limited to at most
- .IR nmc
- bytes (the size of the input buffer), and under conditions where
- \fImbsrtowcs\fR()
- would assign the address just past the last character converted (if any)
- to the pointer object pointed to by
- .IR src ,
- \fImbsnrtowcs\fR()
- shall instead assign the address just past the last byte processed
- (if any) to that pointer object. If the input buffer ends with an
- incomplete character, it is unspecified whether conversion stops at
- the end of the previous character (if any), or at the end of the input
- buffer. In the latter case, a subsequent call to
- \fImbsnrtowcs\fR()
- with an input buffer that starts with the remainder of the incomplete
- character shall correctly complete the conversion of that character.
- .P
- The behavior of these functions shall be affected by the
- .IR LC_CTYPE
- category of the current locale.
- .P
- The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017
- calls these functions.
- .P
- The
- \fImbsnrtowcs\fR()
- and
- \fImbsrtowcs\fR()
- functions need not be thread-safe if called with a NULL
- .IR ps
- argument.
- .P
- The
- \fImbsrtowcs\fR()
- function shall not change the setting of
- .IR errno
- if successful.
- .SH "RETURN VALUE"
- If the input conversion encounters a sequence of bytes that do not form
- a valid character, an encoding error occurs. In this case, these
- functions shall store the value of the macro
- .BR [EILSEQ]
- in
- .IR errno
- and shall return (\fBsize_t\fP)\-1; the conversion state is undefined.
- Otherwise, these functions shall return the number of characters
- successfully converted, not including the terminating null (if any).
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EILSEQ
- An invalid character sequence is detected.
- In the POSIX locale an
- .BR [EILSEQ]
- error cannot occur since all byte values are valid characters.
- .P
- These functions may fail if:
- .TP
- .BR EINVAL
- .IR ps
- points to an object that contains an invalid conversion state.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- A future version may require that when the input buffer ends with
- an incomplete character, conversion stops at the end of the input buffer.
- .SH "SEE ALSO"
- .IR "\fIiconv\fR\^(\|)",
- .IR "\fImbrtowc\fR\^(\|)",
- .IR "\fImbsinit\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<wchar.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .