wcsrtombs.3p (5127B)
- '\" et
- .TH WCSRTOMBS "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
- wcsnrtombs, wcsrtombs
- \(em convert a wide-character string to a character string (restartable)
- .SH SYNOPSIS
- .LP
- .nf
- #include <wchar.h>
- .P
- size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP,
- size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
- size_t wcsrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP,
- size_t \fIlen\fP, mbstate_t *restrict \fIps\fP);
- .fi
- .SH DESCRIPTION
- For
- \fIwcsrtombs\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
- \fIwcsrtombs\fR()
- function shall convert a sequence of wide characters from the array
- indirectly pointed to by
- .IR src
- into a sequence of corresponding characters, beginning in the
- conversion state described by the object pointed to by
- .IR ps .
- If
- .IR dst
- is not a null pointer, the converted characters shall then be
- stored into the array pointed to by
- .IR dst .
- Conversion continues up to and including a terminating null wide
- character, which shall also be stored. Conversion shall stop
- earlier in the following cases:
- .IP " *" 4
- When a code is reached that does not correspond to a valid character
- .IP " *" 4
- When the next character would exceed the limit of
- .IR len
- total bytes to be stored in 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
- \fIwcrtomb\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 wide character) or the address just past
- the last wide character converted (if any). If conversion stopped due
- to reaching a terminating null wide character, the resulting state
- described shall be the initial conversion state.
- .P
- If
- .IR ps
- is a null pointer, the
- \fIwcsrtombs\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
- \fIwcsnrtombs\fR()
- and
- \fIwcsrtombs\fR()
- functions need not be thread-safe if called with a NULL
- .IR ps
- argument.
- .P
- The
- \fIwcsnrtombs\fR()
- function shall be equivalent to the
- \fIwcsrtombs\fR()
- function, except that the conversion is limited to the first
- .IR nwc
- wide characters.
- .P
- The
- \fIwcsrtombs\fR()
- function shall not change the setting of
- .IR errno
- if successful.
- .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 System Interfaces volume of POSIX.1\(hy2017
- calls these functions.
- .SH "RETURN VALUE"
- If conversion stops because a code is reached that does not correspond
- to 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 return (\fBsize_t\fP)\-1; the conversion state is undefined.
- Otherwise, these functions shall return the number of bytes in the
- resulting character sequence, not including the terminating null (if any).
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EILSEQ
- A wide-character code does not correspond to a valid character.
- .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"
- None.
- .SH "SEE ALSO"
- .IR "\fImbsinit\fR\^(\|)",
- .IR "\fIwcrtomb\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 .