L'usage principal de cette fonction est celui avec
s non-NULL et
pwc non-NULL.
Dans ce cas, la fonction
mbrtowc examine au plus
n octets de la séquence commençant en
s,
en extrait le prochain caractère multi-octets complet, et le place en
*pwc.
Elle met à jour l'état de décalage
*ps. Si le caractère large obtenu n'est pas L'\0', elle renvoie
le nombre d'octets lus depuis
s. Si le caractère large obtenu est L'\0', elle réinitialise
l'état de décalage
*ps et renvoie zéro.
Si les
n octets commençant en
s ne contiennent pas de caractère large complet,
mbrtowc
renvoie
(size_t)(-2). Cela peut se produire même si
n >=
MB_CUR_MAX, lorsque la séquence multi-octets
contient des séquences de décalage redondantes.
Si la séquence multi-octets commençant en
s contient une séquence invalide avant le prochain
caractère complet,
mbrtowc renvoie
(size_t)(-1) et place dans
errno la valeur
EILSEQ.
Dans ce cas, les effets sur
*ps sont indéfinis.
Une autre situation est possible, si
s est non-NULL, mais
pwc est NULL. Dans ce cas,
mbrtowc
se comporte comme précédemment, mais n'enregistre pas le caractère large obtenu.
Un troisième cas se présente si
s est NULL. Alors,
pwc et
n sont
ignorés. Si l'état de conversion représenté par
*ps indique une conversion
multi-octets incomplète, la fonction
mbrtowc renvboie
(size_t)(-1), remplie
errno avec
EILSEQ, et
laisse
*ps dans un état indéfini. Sinon, la fonction
mbrtowc function
remet
*ps dans l'état initial et renvoie 0.
Dans tous ces cas, si
ps est un pointeur NULL, une zone de mémoire statique
propre à mbrtowc() est utilisé à sa place.
Sinon,
*ps doit être un objet
mbstate_t valide.
Un tel objet
mbstate_t noté
a peut être initialisé
en le mettant à zéro, par exemple ainsi :
-
memset(&a, 0, sizeof(a));
