.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
.\"
.\" Earlier versions of this page influenced the present text.
.\" It was derived from a Berkeley page with version
.\" @(#)printf.3 6.14 (Berkeley) 7/30/91
.\" converted for Linux by faith@cs.unc.edu, updated by
.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible.
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" .
.\" %%%LICENSE_END
.\"
.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99.
.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes
.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PRINTF 3 "1 novembre 2020" GNU "Manuel du programmeur Linux"
.SH NOM
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf,
vsprintf, vsnprintf \- Formatage des sorties
.SH SYNOPSIS
.nf
\fB#include \fP
.PP
\fBint printf(const char *\fP\fIformat\fP\fB, ...);\fP
\fBint fprintf(FILE *\fP\fIflux\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
\fBint dprintf(int \fP\fIfd\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
\fBint sprintf(char *\fP\fIchaîne\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
\fBint snprintf(char *\fP\fIchaîne\fP\fB, size_t \fP\fItaille\fP\fB, const char *\fP\fIformat\fP\fB, ...);\fP
\fB#include \fP
.PP
\fBint vprintf(const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vfprintf(FILE *\fP\fIflux\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vdprintf(int \fP\fIfd\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vsprintf(char *\fP\fIchaîne\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
\fBint vsnprintf(char *\fP\fIchaîne\fP\fB, size_t \fP\fItaille\fP\fB, const char *\fP\fIformat\fP\fB, va_list \fP\fIap\fP\fB);\fP
.fi
.PP
.RS -4
Exigences de macros de test de fonctionnalités pour la glibc (consulter
\fBfeature_test_macros\fP(7))\ :
.RE
.PP
.ad l
\fBsnprintf\fP(), \fBvsnprintf\fP()\ :
.RS 4
_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
|| /* Versions de la glibc <= 2.19\ : */ _BSD_SOURCE
.RE
.PP
\fBdprintf\fP(), \fBvdprintf\fP()\ :
.PD 0
.RS 4
.TP 4
Depuis la glibc 2.10\ :
_POSIX_C_SOURCE\ >=\ 200809L
.TP
Avant la glibc 2.10\ :
_GNU_SOURCE
.RE
.ad
.PD
.SH DESCRIPTION
The functions in the \fBprintf\fP() family produce output according to a
\fIformat\fP as described below. The functions \fBprintf\fP() and \fBvprintf\fP()
write output to \fIstdout\fP, the standard output stream; \fBfprintf\fP() and
\fBvfprintf\fP() write output to the given output \fIstream\fP; \fBsprintf\fP(),
\fBsnprintf\fP(), \fBvsprintf\fP(), and \fBvsnprintf\fP() write to the character
string \fIstr\fP.
.PP
La fonction \fBdprintf\fP() est équivalente à \fBfprintf\fP() si ce n'est qu'elle
écrit dans un descripteur de fichier \fIfd\fP plutôt que dans un flux \fIstdio\fP.
.PP
Les fonctions \fBsnprintf\fP() et \fBvsnprintf\fP() écrivent au plus \fItaille\fP
octets (octet NULL final («\ \e0\ ») compris) dans \fIchaîne\fP.
.PP
Les fonctions \fBvprintf\fP(), \fBvfprintf\fP(), \fBvdprintf\fP(), \fBvsprintf\fP() et
\fBvsnprintf\fP() sont équivalentes aux fonctions \fBprintf\fP(), \fBfprintf\fP(),
\fBdprintf\fP(), \fBsprintf\fP() et \fBsnprintf\fP() respectivement, mais elles
emploient un tableau \fIva_list\fP à la place d'un nombre variable
d'arguments. Ces fonctions n'appellent pas la macro \fIva_end\fP. Du fait
qu'elles appellent la macro \fIva_arg\fP, la valeur de \fIap\fP n'est pas définie
après l'appel. Consultez \fBstdarg\fP(3).
.PP
Toutes ces fonctions écrivent leurs sorties sous le contrôle d'une chaîne de
\fIformat\fP qui indique les conversions à apporter aux arguments suivants (ou
accessibles à travers les arguments de taille variable de \fBstdarg\fP(3)).
.PP
C99 et POSIX.1\-2001 spécifient que les résultats ne sont pas définis si un
appel à \fBsprintf\fP(), \fBsnprintf\fP(), \fBvsprintf\fP() ou \fBvsnprintf\fP() causait
la copie entre des objets qui se chevauchent (par exemple, si le tableau de
la chaîne cible et un des paramètres d'entrée se trouvent dans le même
tampon). Consultez la section NOTES.
.SS "CHAÎNE DE FORMAT"
Le format de conversion est indiqué par une chaîne de caractères, commençant
et se terminant dans son état de décalage initial. La chaîne de format est
composée de zéro ou plus d'indicateurs\ : les caractères ordinaires
(différents de \fB%\fP), qui sont copiés sans modification sur la sortie, et
les spécifications de conversion, qui chacune recherche un ou plus
d’arguments suivants. Les spécifications de conversion sont introduites par
le caractère \fB%\fP, et se terminent par un \fIindicateur de conversion\fP. Entre
eux peuvent se trouver (dans l'ordre), zéro ou plusieurs \fIattributs\fP, une
valeur optionnelle de \fIlargeur minimale de champ\fP, une valeur optionnelle
de \fIprécision\fP, et un éventuel \fImodificateur de longueur\fP.
.PP
Les arguments doivent correspondre correctement (après les promotions de
types) avec les indicateurs de conversion. Par défaut les arguments sont
pris dans l'ordre indiqué, où chaque «\ *\ » (voir \fILargeur de champ\fP et
\fIPrécision\fP ci\-après) et chaque indicateur de conversion réclame un nouvel
argument (et l'insuffisance d’arguments est une erreur). On peut aussi
préciser explicitement quel argument prendre, en écrivant, à chaque
conversion, «\ %m$\ » au lieu de «\ %\ », et «\ *m$\ » au lieu de «\ *\ ». L'entier décimal \fIm\fP indique la position dans la liste d'arguments,
l'indexation commençant à \fB1\fP. Ainsi,
.PP
.in +4n
.EX
printf("%*d", width, num);
.EE
.in
.PP
et
.PP
.in +4n
.EX
printf("%2$*1$d", width, num);
.EE
.in
.PP
sont équivalents. La seconde notation permet de répéter plusieurs fois le
même argument. Le standard C99 n'autorise pas le style utilisant «\ $\ »,
qui provient des Spécifications UNIX Single. Si le style avec «\ $\ » est
utilisé, il faut l'employer pour toutes conversions prenant un argument, et
pour tous les arguments de largeur et de précision, mais on peut le mélanger
avec des formats «\ %%\ » qui ne consomment pas d'arguments. Il ne doit pas
y avoir de sauts dans les numéros des arguments spécifiés avec «\ $\ ». Par
exemple, si les arguments\ 1 et\ 3 sont spécifiés, l'argument\ 2 doit aussi
être mentionné quelque part dans la chaîne de format.
.PP
Pour certaines conversions numériques, un caractère de séparation décimale
(le point par défaut) est utilisé, ainsi qu'un caractère de regroupement par
milliers. Les véritables caractères dépendent de la valeur de \fBLC_NUMERIC\fP
dans la locale (consultez \fBsetlocale\fP(3)). La localisation POSIX utilise «\ \&.\ » comme séparateur décimal, et n'a pas de caractère de
regroupement. Ainsi,
.PP
.in +4n
.EX
printf("%\(aq.2f", 1234567.89);
.EE
.in
.PP
s'affichera comme «\ 1234567.89\ » dans la localisation POSIX, «\ 1\ 234\ 567,89\ » en localisation fr_FR, et «\ 1.234.567,89\ » en localisation da_DK.
.SS "Caractères d'attribut"
Le caractère % peut être éventuellement suivi par zéro ou plusieurs des
attributs suivants\ :
.TP
\fB#\fP
Indique que la valeur doit être convertie en une autre forme. Pour la
conversion \fBo\fP le premier caractère de la chaîne de sortie vaudra zéro (en
ajoutant un préfixe \fB0\fP si ce n'est pas déjà un zéro). Pour les conversions
\fBx\fP et \fBX\fP un résultat non nul reçoit le préfixe «\ 0x\ » (ou «\ 0X\ »
pour l'indicateur \fBX\fP). Pour les conversions \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP,
\fBF\fP, \fBg\fP et \fBG\fP le résultat contiendra toujours un point décimal même si
aucun chiffre ne le suit (normalement, un point décimal n'est présent avec
ces conversions que si des décimales le suivent). Pour les conversions \fBg\fP
et \fBG\fP les zéros en tête ne sont pas éliminés, contrairement au
comportement habituel. Pour les autres conversions, le résultat est
indéfini.
.TP
\fB\&0\fP
Indique le remplissage avec des zéros. Pour les conversions \fBd\fP, \fBi\fP,
\fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP et \fBG\fP, la
valeur est complétée à gauche par des zéros plutôt que par des espaces. Si
les attributs \fB\&0\fP et \fB\-\fP apparaissent ensemble, l'attribut \fB\&0\fP est
ignoré. Si une précision est fournie avec une conversion numérique (\fBd\fP,
\fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP et \fBX\fP), l'attribut \fB\&0\fP est ignoré. Pour les
autres conversions, le comportement est indéfini.
.TP
\fB\-\fP
Indique que la valeur convertie doit être justifiée sur la limite gauche du
champ (par défaut elle l'est à droite). Les valeurs sont complétées à droite
par des espaces, plutôt qu'à gauche par des zéros ou des espaces. Un
attribut \fB\-\fP surcharge un attribut \fB\&0\fP si les deux sont fournis.
.TP
\fB\(aq \(aq\fP
(une espace) Indique qu'une espace doit être laissée avant un nombre positif
(ou une chaîne vide) produit par une conversion signée
.TP
\fB+\fP
Un signe (\fB+\fP ou \fB\-\fP) doit toujours être imprimé avant un nombre produit
par une conversion signée. Par défaut, un signe n'est utilisé que pour les
valeurs négatives. Un attribut \fB+\fP surcharge un attribut «\ espace\ » si
les deux sont fournis.
.PP
Les cinq caractères d'attributs ci\-dessus sont définis dans la norme C99,
les Spécifications UNIX Single en ajoutent un\ :
.TP
\fB\(aq\fP
Les conversions décimales (\fBi\fP, \fBd\fP, \fBu\fP, \fBf\fP, \fBF\fP, \fBg\fP et \fBG\fP)
indiquent que les chiffres d'un argument numérique doivent être groupés par
milliers en fonction de la localisation (consultez
\fBsetlocale\fP(3)). Remarquez que de nombreuses versions de \fBgcc\fP(1)
n'acceptent pas cet attribut et déclencheront un avertissement (SUSv2
n'inclue pas \fI%\(aqF\fP, mais SUSv3 l'a ajouté).
.PP
La glibc\ 2.2 ajoute un caractère d'attribut supplémentaire.
.TP
\fBI\fP
.\" outdigits keyword in locale file
Pour les conversions décimales (\fBi\fP, \fBd\fP et \fBu\fP), la sortie emploie les
chiffres de la localisation alternative s'il y en a une. Par exemple, depuis
la glibc\ 2.2.3, cela donnera des chiffres arabes pour la localisation perse
(«\ fa_IR\ »).
.SS "Largeur de champ"
Un nombre optionnel ne commençant pas par un zéro, peut indiquer une largeur
minimale de champ. Si la valeur convertie occupe moins de caractères que
cette largeur, elle sera complétée par des espaces à gauche (ou à droite si
l'attribut d'alignement à gauche a été fourni). À la place de la chaîne
représentant le nombre décimal, on peut écrire «\ *\ » ou «\ *m$\ » (\fIm\fP
étant entier) pour indiquer que la largeur du champ est fournie dans
l'argument suivant ou dans le \fIm\fP\-ième argument respectivement. L'argument
fournissant la largeur doit être de type \fIint\fP. Une largeur négative est
considérée comme l'attribut «\ \-\ » vu plus haut suivi d'une largeur
positive. En aucun cas une largeur trop petite ne provoque la troncature du
champ. Si le résultat de la conversion est plus grand que la largeur
indiquée, le champ est élargi pour contenir le résultat.
.SS Précision
Une précision optionnelle, sous la forme d'un point («\ \&.\ ») suivi par
une chaîne optionnelle de nombres décimaux. À la place de la chaîne
représentant le nombre décimal, on peut écrire «\ *\ » ou «\ *m$\ » (\fIm\fP
étant entier) pour indiquer que la précision est fournie dans l'argument
suivant ou dans le \fIm\fP\-ième argument respectivement, et qui doit être de
type \fIint\fP. Si la précision ne contient que le caractère «\ .\ », elle est
considérée comme zéro. Une précision négative est considérée comme
omise. Cette précision indique un nombre minimal de chiffres à faire
apparaître lors des conversions \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP et \fBX\fP, le
nombre de décimales à faire apparaître pour les conversions \fBa\fP, \fBA\fP,
\fBe\fP, \fBE\fP, \fBf\fP et \fBF\fP le nombre maximal de chiffres significatifs pour
\fBg\fP et \fBG\fP et le nombre maximal de caractères à imprimer depuis une chaîne
pour les conversions \fBs\fP et \fBS\fP.
.SS "Modificateur de longueur"
Ici, une «\ conversion d’entier\ » correspond à \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP
ou \fBX\fP.
.TP
\fBhh\fP
La conversion d’entier suivante correspond à un \fIsigned\ char\fP ou
\fIunsigned\ char\fP, ou la conversion \fBn\fP suivante correspond à un pointeur
sur un argument \fIsigned\ char\fP.
.TP
\fBh\fP
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
short\fP argument, or a following \fBn\fP conversion corresponds to a pointer to
a \fIshort\fP argument.
.TP
\fBl\fP
(ell) A following integer conversion corresponds to a \fIlong\fP or \fIunsigned
long\fP argument, or a following \fBn\fP conversion corresponds to a pointer to a
\fIlong\fP argument, or a following \fBc\fP conversion corresponds to a \fIwint_t\fP
argument, or a following \fBs\fP conversion corresponds to a pointer to
\fIwchar_t\fP argument.
.TP
\fBll\fP
(ell\-ell). A following integer conversion corresponds to a \fIlong long\fP or
\fIunsigned long long\fP argument, or a following \fBn\fP conversion corresponds
to a pointer to a \fIlong long\fP argument.
.TP
\fBq\fP
Un synonyme de \fBll\fP. Il s'agit d'une extension non standard, dérivée de
BSD\ ; évitez son utilisation dans du nouveau code.
.TP
\fBL\fP
La conversion \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, \fBg\fP, ou \fBG\fP suivante
correspond à un argument \fIlong\ double\fP (C99 autorise %LF mais pas SUSv2).
.TP
\fBj\fP
La conversion d’entier suivante correspond à un argument \fIintmax_t\fP ou
\fIuintmax_t\fP, ou la conversion \fBn\fP suivante correspond à un pointeur sur un
argument \fIintmax_t\fP.
.TP
\fBz\fP
La conversion d’entier suivante correspond à un argument \fIsize_t\fP ou
\fIssize_t\fP, ou la conversion \fBn\fP suivante correspond à un pointeur sur un
argument \fIsize_t\fP.
.TP
\fBZ\fP
Un synonyme non standard de \fBz\fP qui précède l'apparition de \fBz\fP. Ne pas
l'utiliser dans du nouveau code.
.TP
\fBt\fP
La conversion d’entier suivante correspond à un argument \fIptrdiff_t\fP, ou la
conversion \fBn\fP suivante correspond à un pointeur sur un argument
\fIptrdiff_t\fP.
.PP
SUSv3 mentionne tous les modificateurs précédents à l'exception des
extensions non standard. Les spécifications SUSv2 ne mentionnent que les
modificateurs de longueur \fBh\fP (dans \fBhd\fP, \fBhi\fP, \fBho\fP, \fBhx\fP, \fBhX\fP et
\fBhn\fP), \fBl\fP (dans \fBld\fP, \fBli\fP, \fBlo\fP, \fBlx\fP, \fBlX\fP, \fBln\fP, \fBlc\fP et \fBls\fP)
et \fBL\fP (dans \fBLe\fP, \fBLE\fP, \fBLf\fP, \fBLg\fP et \fBLG\fP).
.PP
.\"
En tant qu’extension non standard, l'implémentation GNU traite \fBll\fP et \fBL\fP
comme des synonymes de façon à ce qu'il soit possible, par exemple, d'écrire
\fBllg\fP (comme synonyme conforme aux standards de \fBLg\fP) et \fBLd\fP (comme
synonyme conforme aux standards de \fBlld\fP). Une telle utilisation n'est pas
portable.
.SS "Indicateurs de conversion"
Un caractère indique le type de conversion à apporter. Les indicateurs de
conversion, et leurs significations sont\ :
.TP
\fBd\fP, \fBi\fP
L'argument \fIint\fP est converti en un chiffre décimal signé. La précision, si
elle est mentionnée, correspond au nombre minimal de chiffres qui doivent
apparaître. Si la conversion fournit moins de chiffres, le résultat est
rempli à gauche avec des zéros. Par défaut la précision
vaut\ \fB1\fP. Lorsque\ \fB0\fP est converti avec une précision valant\ \fB0\fP, la
sortie est vide.
.TP
\fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP
L'argument \fIunsigned int\fP est converti en un chiffre octal non signé
(\fBo\fP), un chiffre décimal non signé (\fBu\fP) ou un chiffre hexadécimal non
signé (\fBx\fP et \fBX\fP). Les lettres \fBabcdef\fP sont utilisées pour les
conversions avec \fBx\fP, les lettres \fBABCDEF\fP sont utilisées pour les
conversions avec \fBX\fP. La précision, si elle est indiquée, donne un nombre
minimal de chiffres à faire apparaître. Si la valeur convertie nécessite
moins de chiffres, elle est complétée à gauche avec des zéros. La précision
par défaut vaut\ \fB1\fP. Lorsque\ \fB0\fP est converti avec une précision
valant\ \fB0\fP, la sortie est vide.
.TP
\fBe\fP, \fBE\fP
L'argument, de type \fIdouble\fP, est arrondi et présenté avec la notation
scientifique [\-]c\fB\&.\fPccc\fBe\fP\(+-cc dans lequel se trouve un chiffre (qui
n'est pas nul si l'argument n'est pas nul) avant le point, puis un nombre de
décimales égal à la précision demandée. Si la précision n'est pas indiquée,
l'affichage contiendra 6\ décimales. Si la précision vaut zéro, il n'y a pas
de point décimal. Une conversion \fBE\fP utilise la lettre \fBE\fP (plutôt que
\fBe\fP) pour introduire l'exposant. Celui\-ci contient toujours au moins deux
chiffres. Si la valeur affichée est nulle, son exposant est 00.
.TP
\fBf\fP, \fBF\fP
L'argument, de type \fIdouble\fP, est arrondi et présenté avec la notation
classique [\-]ccc\fB\&.\fPccc, où le nombre de décimales est égal à la précision
réclamée. Si la précision n'est pas indiquée, l'affichage se fera avec
6\ décimales. Si la précision vaut zéro, aucun point n'est affiché. Lorsque
le point est affiché, il y a toujours au moins un chiffre devant.
.IP
SUSv2 ne mentionne pas \fBF\fP et dit qu'une représentation des chaînes de
caractères pour l'infini ou NaN devrait être disponible. SUSv3 ajoute
l'indicateur \fBF\fP. La norme C99 précise «\ [\-]inf\ » ou «\ [\-]infinity\ »
pour les infinis, et une chaîne commençant par «\ nan\ » pour NaN dans le
cas d'une conversion \fBf\fP, et les chaînes «\ [\-]INF\ », «\ [\-]INFINITY\ » ou
«\ NAN*\ » pour une conversion \fBF\fP.
.TP
\fBg\fP, \fBG\fP
L'argument, de type \fIdouble\fP, est converti en style \fBf\fP ou \fBe\fP (\fBF\fP ou
\fBE\fP pour la conversion \fBG\fP). La précision indique le nombre de décimales
significatives. Si la précision est absente, une valeur par défaut de 6 est
utilisée. Si la précision vaut\ \fB0\fP, elle est considérée comme valant
\fB1\fP. La notation scientifique \fBe\fP est utilisée si l'exposant est inférieur
à \-4 ou supérieur ou égal à la précision demandée. Les zéros en fin de
partie décimale sont supprimés. Un point décimal n'est affiché que s'il est
suivi d'au moins un chiffre.
.TP
\fBa\fP, \fBA\fP
(C99 mais pas SUSv2, mais rajouté dans SUSv3). Pour la conversion \fBa\fP,
l'argument de type \fIdouble\fP est transformé en notation hexadécimale (avec
les lettres abcdef) de forme [\-]\fB0x\fPh\fB\&.\fPhhhh\fBp\fP\(+-\ ; pour la
conversion \fBA\fP, le préfixe \fB0X\fP, les lettres ABCDEF et le séparateur
d'exposant \fBP\fP sont utilisés. Il y a un chiffre hexadécimal avant la
virgule et le nombre de chiffres ensuite est égal à la précision. La
précision par défaut suffit pour une représentation exacte de la valeur, si
une représentation exacte est possible en base\ 2. Sinon, elle est
suffisamment grande pour distinguer les valeurs de type \fIdouble\fP. Le
chiffre avant le point décimal n'est pas spécifié pour les nombres non
normalisés et il est non nul mais non spécifié pour les nombres normalisés.
.TP
\fBc\fP
S'il n'y a pas de modificateur \fBl\fP, l'argument, de type \fIint\fP, est
converti en un \fIunsigned\ char\fP et le caractère correspondant est
affiché. Si un modificateur \fBl\fP est présent, l'argument de type \fIwint_t\fP
(caractère large) est converti en séquence multioctet par un appel à
\fBwcrtomb\fP(3), avec un état de conversion débutant dans l'état initial. La
chaîne multioctet résultante est écrite.
.TP
\fBs\fP
S'il n'y a pas de modificateur \fBl\fP, l'argument de type \fIconst char\ *\fP est
supposé être un pointeur sur un tableau de caractères (pointeur sur une
chaîne). Les caractères du tableau sont écrits jusqu'à l'octet NULL final
(«\ \e0\ »), non compris. Si une précision est indiquée, seul ce nombre de
caractères sont écrits. Si une précision est fournie, il n'y a pas besoin
d'octet NULL. Si la précision n'est pas donnée, ou si elle est supérieure à
la longueur du tableau, l'octet NULL final est nécessaire.
.IP
Si un modificateur \fBl\fP est présent, l'argument de type \fIconst wchar_t\ *\fP
est supposé être un pointeur sur un tableau de caractères larges. Les
caractères larges du tableau sont convertis en une séquence de caractères
multioctets (chacun par un appel de \fBwcrtomb\fP(3), avec un état de
conversion dans l'état initial avant le premier caractère large), cela
jusqu'au caractère large NULL final compris. Les caractères multioctets
résultants sont écrits jusqu'à l’octet NULL final (non compris). Si une
précision est fournie, il n'y a pas plus d'octets écrits que la précision
indiquée, mais aucun caractère multioctet n'est écrit
partiellement. Remarquez que la précision concerne le nombre d'\fIoctets\fP
écrits et non pas le nombre de \fIcaractères larges\fP ou de \fIpositions
d'écrans\fP. La chaîne doit contenir un caractère large NULL final, sauf si
une précision est indiquée et est suffisamment petite pour que le nombre
d'octets écrits la remplisse avant la fin de la chaîne.
.TP
\fBC\fP
(Ni dans C99, ni dans C11, mais dans SUSv2, SUSv3 et SUSv4) Synonyme de
\fBlc\fP. Ne pas utiliser.
.TP
\fBS\fP
(Ni dans C99, ni dans C11, mais dans SUSv2, SUSv3 et SUSv4) Synonyme de
\fBls\fP. Ne pas utiliser.
.TP
\fBp\fP
L'argument pointeur, du type \fIvoid\ *\fP est affiché en hexadécimal, comme
avec \fB%#x\fP ou \fB%#lx\fP.
.TP
\fBn\fP
Le nombre de caractères écrits jusqu'à présent est stocké dans l'entier
pointé par l'argument correspondant. Cet argument doit être un \fIint\ *\fP, ou
une variante dont la taille correspond au modificateur de longueur d'entier
optionnellement fourni. Aucun argument n'est converti (cet indicateur n'est
pas pris en charge par la bibliothèque C Bionic). Le comportement n'est pas
défini si la spécification de conversion comporte un drapeau, une longueur
de champ ou une précision.
.TP
\fBm\fP
(extension glibc\ ; pris en charge par uClibc et musl) Affiche la sortie
\fIstrerror(errno)\fP. Aucun argument n'est requis.
.TP
\fB%\fP
Un caractère «\ %\ » est écrit. Il n'y a pas de conversion. L'indicateur
complet est «\ %%\ ».
.SH "VALEUR RENVOYÉE"
En cas de succès, ces fonctions renvoient le nombre de caractères affichés
(sans compter l'octet NULL final utilisé pour terminer les sorties dans les
chaînes).
.PP
Les fonctions \fBsnprintf\fP() et \fBvsnprintf\fP() n'écrivent pas plus de
\fItaille\fP octets (y compris l'octet NULL final). Si la sortie a été tronquée
à cause de la limite, la valeur de retour est le nombre de caractères (octet
NULL final non compris) qui auraient été écrits dans la chaîne s'il y avait
eu suffisamment de place. Ainsi, une valeur de retour \fItaille\fP ou plus
signifie que la sortie a été tronquée (consultez aussi la section \fBNOTES\fP
plus bas).
.PP
Si une erreur de sortie s'est produite, une valeur négative est renvoyée.
.SH ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter
\fBattributes\fP(7).
.TS
allbox;
lbw23 lb lb
l l l.
Interface Attribut Valeur
T{
\fBprintf\fP(),
\fBfprintf\fP(),
.br
\fBsprintf\fP(),
\fBsnprintf\fP(),
.br
\fBvprintf\fP(),
\fBvfprintf\fP(),
.br
\fBvsprintf\fP(),
\fBvsnprintf\fP()
T} Sécurité des threads MT\-Safe locale
.TE
.sp 1
.SH CONFORMITÉ
\fBfprintf\fP(), \fBprintf\fP(), \fBsprintf\fP(), \fBvprintf\fP(), \fBvfprintf\fP(),
\fBvsprintf\fP()\ : POSIX.1\-2001, POSIX.1\-2008, C89, C99.
.PP
\fBsnprintf\fP(), \fBvsnprintf\fP()\ : POSIX.1\-2001, POSIX.1\-2008, C99.
.PP
\fBdprintf\fP() et \fBvdprintf\fP() sont originellement des extensions GNU. Elles
ont été standardisées dans POSIX.1\-2008.
.PP
.\" .PP
.\" Linux libc4 knows about the five C standard flags.
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" and the conversions
.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP,
.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP,
.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP,
.\" where \fBF\fP is a synonym for \fBf\fP.
.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms
.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP.
.\" (This is bad, and caused serious bugs later, when
.\" support for \fB%D\fP disappeared.)
.\" No locale-dependent radix character,
.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
.\" .PP
.\" Linux libc5 knows about the five C standard flags and the \(aq flag,
.\" locale, "%m$" and "*m$".
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP
.\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug).
.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP,
.\" but adds the conversion character
.\" .BR m ,
.\" which outputs
.\" .IR strerror(errno) .
.\" .PP
.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
En ce qui concerne la valeur de retour de \fBsnprintf\fP(), SUSv2 et C99 sont
en contradiction\ : lorsque \fBsnprintf\fP() est appelée avec un argument
\fItaille\fP=\fI0\fP, SUSv2 précise une valeur de retour indéterminée, inférieure
à 1, alors que C99 autorise \fIchaîne\fP à être NULL dans ce cas, et renvoie
(comme toujours) le nombre de caractères qui auraient été écrits si la
chaîne de sortie avait été assez grande. Les spécifications de \fBsnprintf\fP()
dans POSIX.1\-2001 et ses versions supérieures sont alignées avec C99.
.PP
La bibliothèque glibc\ 2.1 ajoute les modificateurs de longueur \fBhh\fP, \fBj\fP,
\fBt\fP et \fBz\fP, et les caractères de conversion \fBa\fP et\ \fBA\fP.
.PP
La bibliothèque glibc\ 2.2. ajoute le caractère de conversion \fBF\fP avec la
sémantique C99, et le caractère d'attribut\ \fBI\fP.
.SH NOTES
Certains programmes reposent imprudemment sur du code comme\ :
.PP
sprintf(buf, "%s texte supplémentaire", buf);
.PP
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075
pour ajouter du texte à \fIbuf\fP. Cependant, les normes indiquent
explicitement que le résultat n'est pas défini si les tampons de source et
de destination se recouvrent lors d'un appel à \fBsprintf\fP(), \fBsnprintf\fP(),
\fBvsprintf\fP() et \fBvsnprintf\fP(). En fonction de la version de \fBgcc\fP(1)
utilisée et des options de compilation, ces appels ne produiront \fBpas\fP le
résultat attendu.
.PP
.\" .SH HISTORY
.\" UNIX V7 defines the three routines
.\" .BR printf (),
.\" .BR fprintf (),
.\" .BR sprintf (),
.\" and has the flag \-, the width or precision *, the length modifier l,
.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags
.\" #, + and and no longer mentions D,O,U,X.
.\" 2.11BSD has
.\" .BR vprintf (),
.\" .BR vfprintf (),
.\" .BR vsprintf (),
.\" and warns not to use D,O,U,X.
.\" 4.3BSD Reno has the flag 0, the length modifiers h and L,
.\" and the conversions n, p, E, G, X (with current meaning)
.\" and deprecates D,O,U.
.\" 4.4BSD introduces the functions
.\" .BR snprintf ()
.\" and
.\" .BR vsnprintf (),
.\" and the length modifier q.
.\" FreeBSD also has functions
.\" .BR asprintf ()
.\" and
.\" .BR vasprintf (),
.\" that allocate a buffer large enough for
.\" .BR sprintf ().
.\" In glibc there are functions
.\" .BR dprintf ()
.\" and
.\" .BR vdprintf ()
.\" that print to a file descriptor instead of a stream.
L'implémentation des fonctions \fBsnprintf\fP() et \fBvsnprintf\fP() de la glibc
se conforme à la norme C99, et se comporte comme décrit plus haut depuis la
glibc\ 2.1. Jusqu'à la glibc\ 2.0.6, elles renvoyaient \fB\-1\fP si la sortie
avait été tronquée.
.SH BOGUES
.\" .PP
.\" Linux libc4.[45] does not have a
.\" .BR snprintf (),
.\" but provides a libbsd that contains an
.\" .BR snprintf ()
.\" equivalent to
.\" .BR sprintf (),
.\" that is, one that ignores the
.\" .I size
.\" argument.
.\" Thus, the use of
.\" .BR snprintf ()
.\" with early libc4 leads to serious security problems.
Comme \fBsprintf\fP() et \fBvsprintf\fP() ne font pas de suppositions sur la
longueur des chaînes, le programme appelant doit s'assurer de ne pas
déborder l'espace d'adressage. C'est souvent difficile. Notez que la
longueur des chaînes peut varier avec la localisation et être difficilement
prévisible. Il faut alors utiliser \fBsnprintf\fP() ou \fBvsnprintf\fP() à la
place (ou encore \fBasprintf\fP(3) et \fBvasprintf\fP(3)).
.PP
.\" .PP
.\" Some floating-point conversions under early libc4
.\" caused memory leaks.
Un code tel que \fBprintf(\fP\fItoto\fP\fB);\fP indique souvent un bogue, car \fItoto\fP
peut contenir un caractère «\ %\ ». Si \fItoto\fP vient d'une saisie non
sécurisée, il peut contenir \fB%n\fP, ce qui autorise \fBprintf\fP() à écrire dans
la mémoire, et crée une faille de sécurité.
.SH EXEMPLES
Pour afficher \fIPi\fP avec cinq décimales\ :
.PP
.in +4n
.EX
#include
#include
fprintf (stdout, "pi = %.5f\en", 4 * atan (1.0));
.EE
.in
.PP
Pour afficher une date et une heure sous la forme «\ Sunday, July 3, 23:15\ », ou \fIjour_semaine\fP et \fImois\fP sont des pointeurs sur des chaînes\ :
.PP
.in +4n
.EX
#include
fprintf(stdout, "%s, %s %d, %.2d:%.2d\en",
jour_semaine, mois, jour, heure, minute);
.EE
.in
.PP
De nombreux pays utilisent un format de date différent, comme
jour\-mois\-année. Une version internationale doit donc être capable
d'afficher les arguments dans l'ordre indiqué par le format\ :
.PP
.in +4n
.EX
#include
fprintf(stdout, format,
jour_semaine, mois, jour, heure, min);
.EE
.in
.PP
où le \fIformat\fP dépend de la localisation et peut permuter les
arguments. Avec la valeur\ :
.PP
.in +4n
.EX
"%1$s, %3$d. %2$s, %4$d:%5$.2d\fr"
.EE
.in
.PP
On peut obtenir «\ Dimanche, 3\ juillet, 23:15\ ».
.PP
Pour allouer une chaîne de taille suffisante et écrire dedans (code correct
aussi bien pour la glibc\ 2.0 que la glibc\ 2.1)\ :
.PP
.EX
#include
#include
#include
char *
make_message(const char *fmt, ...)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;
/* Déterminer la taille requise */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
/* One extra byte for \(aq\e0\(aq */
size = (size_t) n + 1;
p = malloc(size);
if (p == NULL)
return NULL;
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0) {
free(p);
return NULL;
}
return p;
}
.EE
.PP
En cas de troncature dans les versions de la glibc avant la\ 2.0.6, c'est
traité comme une erreur au lieu d'être traité de façon élégante.
.SH "VOIR AUSSI"
\fBprintf\fP(1), \fBasprintf\fP(3), \fBputs\fP(3), \fBscanf\fP(3), \fBsetlocale\fP(3),
\fBstrfromd\fP(3), \fBwcrtomb\fP(3), \fBwprintf\fP(3), \fBlocale\fP(5)
.SH COLOPHON
Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP
Linux. Une description du projet et des instructions pour signaler des
anomalies et la dernière version de cette page peuvent être trouvées à
l'adresse \%https://www.kernel.org/doc/man\-pages/.
.SH TRADUCTION
La traduction française de cette page de manuel a été créée par
Christophe Blaess ,
Stéphan Rafin ,
Thierry Vignaud ,
François Micaux,
Alain Portal ,
Jean-Philippe Guérard ,
Jean-Luc Coulon (f5ibh) ,
Julien Cristau ,
Thomas Huriaux ,
Nicolas François ,
Florentin Duneau ,
Simon Paillard ,
Denis Barbier ,
David Prévot ,
Frédéric Hantrais
et
Grégoire Scano
.
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
.MT
debian-l10n-french@lists.debian.org
.ME .