original/man3/wcstombs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .TH WCSTOMBS 3  1999-07-25 "GNU" "Linux Programmer's Manual"
  15 .SH NAME
  16 wcstombs \- convert a wide-character string to a multibyte string
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <stdlib.h>
  20 .sp
  21 .BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n );
  22 .fi
  23 .SH DESCRIPTION
  24 If \fIdest\fP is not a NULL pointer, the
  25 .BR wcstombs ()
  26 function converts
  27 the wide-character string \fIsrc\fP to a multibyte string starting at
  28 \fIdest\fP.
  29 At most \fIn\fP bytes are written to \fIdest\fP.
  30 The conversion
  31 starts in the initial state.
  32 The conversion can stop for three reasons:
  33 .PP
  34 1. A wide character has been encountered that can not be represented as a
  35 multibyte sequence (according to the current locale).
  36 In this case
  37 .I (size_t)\ \-1
  38 is returned.
  39 .PP
  40 2. The length limit forces a stop.
  41 In this case the number of bytes written to
  42 \fIdest\fP is returned, but the shift state at this point is lost.
  43 .PP
  44 3. The wide-character string has been completely converted, including the
  45 terminating L\(aq\\0\(aq.
  46 In this case the conversion ends in the initial state.
  47 The number of bytes written to \fIdest\fP,
  48 excluding the terminating \(aq\\0\(aq byte, is returned.
  49 .PP
  50 The programmer must ensure that there is room for at least \fIn\fP bytes
  51 at \fIdest\fP.
  52 .PP
  53 If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as
  54 above, except that the converted bytes are not written out to memory,
  55 and that no length limit exists.
  56 .PP
  57 In order to avoid the case 2 above, the programmer should make sure \fIn\fP
  58 is greater or equal to \fIwcstombs(NULL,src,0)+1\fP.
  59 .SH "RETURN VALUE"
  60 The
  61 .BR wcstombs ()
  62 function returns the number of bytes that make up the
  63 converted part of multibyte sequence, not including the terminating null byte.
  64 If a wide character was encountered which could not be
  65 converted,
  66 .I (size_t)\ \-1
  67 is returned.
  68 .SH "CONFORMING TO"
  69 C99.
  70 .SH NOTES
  71 The behavior of
  72 .BR wcstombs ()
  73 depends on the
  74 .B LC_CTYPE
  75 category of the
  76 current locale.
  77 .PP
  78 The function
  79 .BR wcsrtombs (3)
  80 provides a thread safe interface to
  81 the same functionality.
  82 .SH "SEE ALSO"
  83 .BR wcsrtombs (3)