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()
renvoie
(size_t) -1,
remplit
errno
avec
EILSEQ,
et laisse
*ps dans un état indéfini.
Sinon, la fonction
mbrtowc()
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));