xref: /illumos-gate/usr/src/man/man3c/wcstombs.3c (revision bbf215553c7233fbab8a0afdf1fac74c44781867)

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2017 Nexenta Systems, Inc.
.\"
.Dd March 28, 2017
.Dt WCSTOMBS 3C
.Os
.Sh NAME
.Nm wcstombs ,
.Nm wcstombs_l
.Nd convert a wide-character string to a multibyte character string
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdlib.h
.Ft size_t
.Fo wcstombs
.Fa "char *restrict s"
.Fa "const wchar_t *restrict pwcs"
.Fa "size_t n"
.Fc
.In stdlib.h
.In xlocale.h
.Ft size_t
.Fo wcstombs_l
.Fa "char *restrict s"
.Fa "const wchar_t *restrict pwcs"
.Fa "size_t n"
.Fa "locale_t loc"
.Fc
.Sh DESCRIPTION
The
.Fn wcstombs
function converts a wide-character string
.Fa pwcs
into a multibyte character string, beginning in the initial conversion state.
If
.Fa s
is not
.Dv NULL ,
converted characters are stored into the array pointed to by
.Fa s .
.Pp
Conversion continues up to and including a terminating null wide-character,
which is also stored, or until
.Fa n
bytes have been stored into the array pointed to by
.Fa s .
If the latter case results in partial multibyte character at the end of the
string, it is not stored.
.Pp
The behavior of
.Fn wcstombs
function is affected by the
.Ev LC_CTYPE
category of the current locale.
.Pp
The
.Fn wcstombs_l
function behaves identically to
.Fn wcstombs ,
except instead of using the current locale, it uses the locale as specified by
.Fa loc .
.Sh RETURN VALUES
The
.Fn wcstombs
and
.Fn wcstombs_l
functions return the number of bytes in the resulting character sequence, not
including the terminating null
.Pq if any ,
or
.Li \-1
if a code is reached that does not correspond to a valid character.
.Sh ERRORS
The
.Fn wcstombs
and
.Fn wcstombs_l
functions will fail if:
.Bl -tag -width Er
.It Er EILSEQ
A wide-character code does not correspond to a valid character.
.It Er EINVAL
The conversion state is invalid.
.El
.Sh INTERFACE STABILITY
The
.Fn wcstombs
function is
.Sy Standard .
The
.Fn wcstombs_l
function is
.Sy Uncommitted .
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr mbstowcs 3C ,
.Xr newlocale 3C ,
.Xr setlocale 3C ,
.Xr uselocale 3C ,
.Xr wcsnrtombs 3C ,
.Xr wctomb 3C ,
.Xr attributes 7 ,
.Xr environ 7 ,
.Xr standards 7