MBTOWC(3)

NAME
mbtowc - minimal multibyte to wide char converter

SYNOPSIS

#include <stdlib.h>

int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n);

DESCRIPTION

When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming implementation of mbtowc. In this case, only ``multi-byte character sequences'' recognized are single bytes, and they are ``converted'' to themselves. Each call to mbtowc copies one character from *s to *pwc, unless s is a null pointer. The argument n is ignored.

When _MB_CAPABLE is defined, this routine calls _mbtowc_r to perform the conversion, passing a state variable to allow state dependent decoding. The result is based on the locale setting which may be restricted to a defined set of locales.

RETURNS

This implementation of mbtowc returns 0 if s is NULL or is the empty string; it returns 1 if not _MB_CAPABLE or the character is a single-byte character; it returns -1 if n is 0 or the multi-byte character is invalid; otherwise it returns the number of bytes in the multibyte character. If the return value is -1, no changes are made to the pwc output string. If the input is the empty string, a wchar_t nul is placed in the output string and 0 is returned. If the input has a length of 0, no changes are made to the pwc output string.

PORTABILITY

mbtowc is required in the ANSI C standard. However, the precise effects vary with the locale.

mbtowc requires no supporting OS subroutines.

AUTHORS

Steve Chamberlain
    Author.

Roland Pesch
    Author.

Red Hat Support

Jeff Johnston
    Author.

COPYRIGHT

This file documents the ANSI C library.

Copyright (C) 1992, 1993, 1994-2014 Red Hat, Inc.

libc includes software developed by the University of California, Berkeley and its contributors.

libc includes software developed by Martin Jackson, Graham Haley and Steve Chamberlain of Tadpole Technology and released to Cygnus.

libc uses floating-point conversion software developed at AT&T, which includes this copyright information:

The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, subject to the terms of the GNU General Public License, which includes the provision that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.