printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf,
- Provided by: manpages-fr-dev (Version: 4.29.1-1)
- Source: manpages-l10n
- Report a bug
Bibliothèque C standard (libc, -lc)
#include <stdio.h>
int printf(const char *restrict format, ...);
int fprintf(FILE *restrict stream,
const char *restrict format, ...);
int dprintf(int fd,
const char *restrict format, ...);
int sprintf(char *restrict str,
const char *restrict format, ...);
int snprintf(size_t size;
char str[restrict size], size_t size,
const char *restrict format, ...);
int vprintf(const char *restrict format, va_list ap);
int vfprintf(FILE *restrict stream,
const char *restrict format, va_list ap);
int vdprintf(int fd,
const char *restrict format, va_list ap);
int vsprintf(char *restrict str,
const char *restrict format, va_list ap);
int vsnprintf(size_t size;
char str[restrict size], size_t size,
const char *restrict format, va_list ap);
snprintf(), vsnprintf() :
_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
|| /* glibc <= 2.19 : */ _BSD_SOURCE
dprintf(), vdprintf() :
Depuis la glibc 2.10 :
_POSIX_C_SOURCE >= 200809L
Avant la glibc 2.10 :
_GNU_SOURCE
Les fonctions de la famille printf() produisent des sorties en accord avec le format décrit plus bas. Les fonctions printf() et vprintf() écrivent leur sortie sur stdout, le flux de sortie standard. fprintf() et vfprintf() écrivent sur le flux flux indiqué. sprintf(), snprintf(), vsprintf() et vsnprintf() écrivent leurs sorties dans la chaîne de caractères chaîne.
La fonction dprintf() est équivalente à fprintf() si ce n'est qu'elle écrit dans un descripteur de fichier fd plutôt que dans un flux stdio(3).
The functions snprintf() and vsnprintf() write at most size bytes (including the terminating null byte ('\0')) to str.
Les fonctions vprintf(), vfprintf(), vdprintf(), vsprintf() et vsnprintf() sont équivalentes aux fonctions printf(), fprintf(), dprintf(), sprintf() et snprintf() respectivement, mais elles emploient un tableau va_list à la place d'un nombre variable d'arguments. Ces fonctions n'appellent pas la macro va_end. Du fait qu'elles appellent la macro va_arg, la valeur de ap n'est pas définie après l'appel. Consultez stdarg(3).
Toutes ces fonctions écrivent leurs sorties sous le contrôle d'une chaîne de format qui indique les conversions à apporter aux arguments suivants (ou accessibles à travers les fonctions d'argument de taille variable de stdarg(3)).
C99 et POSIX.1-2001 spécifient que les résultats ne sont pas définis si un appel à sprintf(), snprintf(), vsprintf() ou vsnprintf() 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 AVERTISSEMENTS
La chaîne de format est une chaîne de caractères, commençant et se terminant dans son état de décalage initial, si présent. La chaîne de format est composée de zéro ou plus d'indicateurs : les caractères ordinaires (différents de %), qui sont copiés sans modification sur la sortie, et les spécifications de conversion, qui chacune recherche zéro ou plus d’arguments suivants. Les spécifications de conversion sont introduites par le caractère % et se terminent par un indicateur de conversion. Entre eux peuvent se trouver (dans l'ordre), zéro ou plusieurs attributs, une valeur optionnelle de largeur minimale de champ, une valeur optionnelle de précision et un éventuel modificateur de longueur.
La syntaxe générale d'un format de conversion est :
%[argument$][flags][width][.precision][length modifier]conversion
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 Largeur de champ et Précision ci-après) et chaque indicateur de conversion réclament 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 m indique la position dans la liste d'arguments, l'indexation commençant à 1. Ainsi,
printf("%*d", largeur, numéro);
et
printf("%2$*1$d", largeur, numéro);
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.
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 millier. Les véritables caractères dépendent de la valeur de LC_NUMERIC dans la locale (consultez setlocale(3)). La localisation POSIX utilise « . » comme séparateur décimal, et n'a pas de caractère de regroupement. Ainsi,
printf("%'.2f", 1234567.89);
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.
Le caractère % peut être éventuellement suivi par zéro ou plusieurs des attributs suivants :
The five flag characters above are defined in the C99 standard. POSIX specifies one further flag character.
La glibc 2.2 ajoute un caractère d'attribut supplémentaire.
An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the field width is given in the next argument, or in the m-th argument, respectively, which must be of type int. A negative field width is taken as a '-' flag followed by a positive field width. In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
An optional precision, in the form of a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the precision is given in the next argument, or in the m-th argument, respectively, which must be of type int. If the precision is given as just '.', the precision is taken to be zero. A negative precision is taken as if the precision were omitted. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the radix character for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s and S conversions.
Ici, une « conversion d’entier » correspond à d, i, o, u, x ou X.
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 h (dans hd, hi, ho, hx, hX et hn), l (dans ld, li, lo, lx, lX, ln, lc et ls) et L (dans Le, LE, Lf, Lg et LG).
En tant qu’extension non standard, l'implémentation GNU traite ll et L comme des synonymes de façon à ce qu'il soit possible, par exemple, d'écrire llg (comme synonyme conforme aux standards de Lg) et Ld (comme synonyme conforme aux standards de lld). Une telle utilisation n'est pas portable.
Un caractère indique le type de conversion à apporter. Les indicateurs de conversion et leurs significations sont :
En cas de succès, ces fonctions renvoient le nombre d'octets affichés (sans compter l'octet NULL final utilisé pour terminer les sorties dans les chaînes).
The functions snprintf() and vsnprintf() do not write more than size bytes (including the terminating null byte ('\0')). If the output was truncated due to this limit, then the return value is the number of characters (excluding the terminating null byte) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. (See also below under CAVEATS.)
On error, a negative value is returned, and errno is set to indicate the error.
See write(2) and putwc(3). In addition, the following error may occur:
The dprintf() function may fail additionally if:
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
| Interface | Attribut | Valeur |
| printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf() | Sécurité des threads | MT-Safe locale |
Issue 4 of the X/Open Portability Guide (SUSv1, 1994) adds '.
La bibliothèque glibc 2.1 ajoute les modificateurs de longueur hh, j, t et z et les caractères de conversion a et A.
La bibliothèque glibc 2.2 ajoute le caractère de conversion F avec la sémantique C99 et le caractère d'attribut I.
glibc 2.35 donne une signification à la forme alternative (#) du spécificateur de conversion m, c'est-à-dire %#m.
Certains programmes reposent imprudemment sur du code comme :
sprintf(buf, "%s texte supplémentaire", buf);
pour ajouter du texte à buf. 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 à sprintf(), snprintf(), vsprintf() et vsnprintf(). En fonction de la version de gcc(1) utilisée et des options de compilation, ces appels ne produiront pas le résultat attendu.
L'implémentation des fonctions snprintf() et vsnprintf() 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 -1 si la sortie avait été tronquée.
Comme sprintf() et vsprintf() supposent des chaînes de longueur arbitraire, le programme appelant doit s'assurer de ne pas déborder l'espace d'adressage. C'est souvent difficile. Notez que la taille des chaînes peut varier avec la localisation et être difficilement prévisible. Il faut alors utiliser snprintf() ou vsnprintf() à la place (ou encore asprintf(3) et vasprintf(3)).
Un code tel que printf(toto); indique souvent un bogue, car toto peut contenir un caractère « % ». Si toto vient d'une saisie non sécurisée, il peut contenir %n, ce qui autorise printf() à écrire dans la mémoire, et crée une faille de sécurité.
Pour afficher Pi avec cinq décimales :
#include <math.h> #include <stdio.h> fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
Pour afficher une date et une heure sous la forme « Sunday, July 3, 23:15 », où jour_semaine et mois sont des pointeurs sur des chaînes :
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
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 :
#include <stdio.h>
fprintf(stdout, format,
jour_semaine, mois, jour, heure, min);
où le format dépend de la localisation et peut permuter les arguments. Avec la valeur :
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
one might obtain "Sonntag, 3. Juli, 10:02".
Pour allouer une chaîne de taille suffisante et écrire dedans (code correct aussi bien pour la glibc 2.0 que pour la glibc 2.1) :
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *
make_message(const char *fmt, ...)
{
int n = 0;
size_t size = 0;
char *p = NULL;
va_list ap;
/* Determine required size. */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
size = (size_t) n + 1; /* One extra byte for '\0' */
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;
}
En cas de troncature dans les versions de la glibc avant la glibc 2.0.6, c'est traité comme une erreur au lieu d'être traité de façon élégante.
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org>, Frédéric Hantrais <fhantrais@gmail.com>, Grégoire Scano <gregoire.scano@malloc.fr> et Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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 à debian-l10n-french@lists.debian.org.