printf(3) Library Functions Manual printf(3) NOM printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf -- Formatage des sorties BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include 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); Exigences de macros de test de fonctionnalites pour la glibc (consulter feature_test_macros(7)) : 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 DESCRIPTION Les fonctions de la famille printf() produisent des sorties en accord avec le format decrit plus bas. Les fonctions printf() et vprintf() ecrivent leur sortie sur stdout, le flux de sortie standard. fprintf() et vfprintf() ecrivent sur le flux flux indique. sprintf(), snprintf(), vsprintf() et vsnprintf() ecrivent leurs sorties dans la chaine de caracteres chaine. La fonction dprintf() est equivalente a fprintf() si ce n'est qu'elle ecrit dans un descripteur de fichier fd plutot 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 equivalentes aux fonctions printf(), fprintf(), dprintf(), sprintf() et snprintf() respectivement, mais elles emploient un tableau va_list a 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 definie apres l'appel. Consultez stdarg(3). Toutes ces fonctions ecrivent leurs sorties sous le controle d'une chaine de format qui indique les conversions a apporter aux arguments suivants (ou accessibles a travers les fonctions d'argument de taille variable de stdarg(3)). C99 et POSIX.1-2001 specifient que les resultats ne sont pas definis si un appel a sprintf(), snprintf(), vsprintf() ou vsnprintf() causait la copie entre des objets qui se chevauchent (par exemple, si le tableau de la chaine cible et un des parametres d'entree se trouvent dans le meme tampon). Consultez la section AVERTISSEMENTS CHAINE DE FORMAT La chaine de format est une chaine de caracteres, commencant et se terminant dans son etat de decalage initial, si present. La chaine de format est composee de zero ou plus d'indicateurs : les caracteres ordinaires (differents de %), qui sont copies sans modification sur la sortie, et les specifications de conversion, qui chacune recherche zero ou plus d'arguments suivants. Les specifications de conversion sont introduites par le caractere % et se terminent par un indicateur de conversion. Entre eux peuvent se trouver (dans l'ordre), zero ou plusieurs attributs, une valeur optionnelle de largeur minimale de champ, une valeur optionnelle de precision et un eventuel modificateur de longueur. La syntaxe generale d'un format de conversion est : %[argument$][flags][width][.precision][length modifier]conversion Les arguments doivent correspondre correctement (apres les promotions de types) avec les indicateurs de conversion. Par defaut les arguments sont pris dans l'ordre indique, ou chaque << * >> (voir Largeur de champ et Precision ci-apres) et chaque indicateur de conversion reclament un nouvel argument (et l'insuffisance d'arguments est une erreur). On peut aussi preciser explicitement quel argument prendre, en ecrivant, a chaque conversion, << %m$ >> au lieu de << % >>, et << *m$ >> au lieu de << * >>. L'entier decimal m indique la position dans la liste d'arguments, l'indexation commencant a 1. Ainsi, printf("%*d", largeur, numero); et printf("%2$*1$d", largeur, numero); sont equivalents. La seconde notation permet de repeter plusieurs fois le meme argument. Le standard C99 n'autorise pas le style utilisant << $ >>, qui provient des Specifications UNIX Single. Si le style avec << $ >> est utilise, il faut l'employer pour toutes conversions prenant un argument et pour tous les arguments de largeur et de precision, mais on peut le melanger avec des formats << %% >> qui ne consomment pas d'arguments. Il ne doit pas y avoir de sauts dans les numeros des arguments specifies avec << $ >>. Par exemple, si les arguments 1 et 3 sont specifies, l'argument 2 doit aussi etre mentionne quelque part dans la chaine de format. Pour certaines conversions numeriques, un caractere de separation decimale (le point par defaut) est utilise, ainsi qu'un caractere de regroupement par millier. Les veritables caracteres dependent de la valeur de LC_NUMERIC dans la locale (consultez setlocale(3)). La localisation POSIX utilise << . >> comme separateur decimal, et n'a pas de caractere 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. Caracteres d'attribut Le caractere % peut etre eventuellement suivi par zero ou plusieurs des attributs suivants : # Indique que la valeur doit etre convertie en une autre forme. Pour les conversions o le premier caractere de la chaine de sortie vaudra zero (en ajoutant un prefixe 0 si ce n'est pas deja un zero). Pour les conversions x et X un resultat non nul recoit le prefixe << 0x >> (ou << 0X >> pour l'indicateur X). Pour les conversions a, A, e, E, f, F, g et G, le resultat contiendra toujours un point decimal meme si aucun chiffre ne le suit (normalement, un point decimal n'est present avec ces conversions que si des decimales le suivent). Pour les conversions g et G, les zeros en fin ne sont pas elimines, contrairement au comportement habituel. Pour m, si errno contient un code d'erreur valable, la sortie de strerrorname_np(errno) est affichee ; autrement, la valeur stockee dans errno est affichee sous la forme d'un nombre decimal. Pour les autres conversions, le resultat est indefini. 0 Indique le remplissage avec des zeros. Pour les conversions d, i, o, u, x, X, a, A, e, E, f, F, g et G, la valeur est completee a gauche par des zeros plutot que par des espaces. Si les attributs 0 et - apparaissent ensemble, l'attribut 0 est ignore. Si une precision est fournie avec une conversion entiere (d, i, o, u, x et X), l'attribut 0 est ignore. Pour les autres conversions, le comportement est indefini. - Indique que la valeur convertie doit etre justifiee sur la limite gauche du champ (par defaut elle l'est a droite). Les valeurs sont completees a droite par des espaces, plutot qu'a gauche par des zeros ou des espaces. Un attribut - surcharge un attribut 0 si les deux sont fournis. ' ' (une espace) Un blanc indique qu'une espace doit etre laissee avant un nombre positif (ou une chaine vide) produit par une conversion signee + Un signe (+ ou -) doit toujours etre place avant un nombre produit par une conversion signee. Par defaut, un signe n'est utilise que pour les valeurs negatives. Un attribut + surcharge un attribut << espace >> si les deux sont fournis. The five flag characters above are defined in the C99 standard. POSIX specifies one further flag character. ' For decimal conversion (i, d, u, f, F, g, G) the output is to be grouped with thousands' grouping characters as a non-monetary quantity. Misleadingly, this isn't necessarily every thousand: for example Karbi ("mjw_IN"), groups its digits into 3 once, then 2 repeatedly. Compare locale(7) grouping and thousands_sep, contrast with mon_grouping/mon_thousands_sep and strfmon(3). This is a no-op in the default "C" locale. La glibc 2.2 ajoute un caractere d'attribut supplementaire. I Pour les conversions decimales (i, d et u), 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 >>). Largeur de champ 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. Precision 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. Modificateur de longueur Ici, une << conversion d'entier >> correspond a d, i, o, u, x ou X. hh La conversion d'entier suivante correspond a un signed char ou a un unsigned char, ou la conversion n suivante correspond a un pointeur sur un argument signed char. h La conversion d'entier suivante correspond a un short ou a un unsigned short, ou la conversion n suivante correspond a un pointeur sur un argument short. l (lettre l) La conversion d'entier suivante correspond a un argument long ou unsigned long, ou la conversion n suivante correspond a un pointeur sur un argument long, ou la conversion c suivante correspond a un argument wint_t, ou encore la conversion s suivante correspond a un pointeur sur un argument wchar_t. Lors de la conversion a, A, e, E, f, F, g ou G suivante, ce modificateur de longueur est ignore (C99 ; pas dans SUSv2). ll (lettre l en double). La conversion d'entier suivante correspond a un long long ou a un unsigned long long, ou la conversion n suivante correspond a un pointeur sur un long long. q Un synonyme de ll. Il s'agit d'une extension non standard, derivee de BSD ; evitez son utilisation dans du nouveau code. L La conversion a, A, e, E, f, F, g ou G suivante correspond a un argument long double (C99 autorise %LF mais pas SUSv2). j La conversion d'entier suivante correspond a un argument intmax_t ou uintmax_t, ou la conversion n suivante correspond a un pointeur sur un argument intmax_t. z La conversion d'entier suivante correspond a un argument size_t ou ssize_t, ou la conversion n suivante correspond a un pointeur sur un argument size_t. Z Un synonyme non standard de z qui precede l'apparition de z. Ne pas l'utiliser dans du nouveau code. t La conversion d'entier suivante correspond a un argument ptrdiff_t, ou la conversion n suivante correspond a un pointeur sur un argument ptrdiff_t. SUSv3 mentionne tous les modificateurs precedents a l'exception des extensions non standard. Les specifications 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'implementation GNU traite ll et L comme des synonymes de facon a ce qu'il soit possible, par exemple, d'ecrire llg (comme synonyme conforme aux standards de Lg) et Ld (comme synonyme conforme aux standards de lld). Une telle utilisation n'est pas portable. Indicateurs de conversion Un caractere indique le type de conversion a apporter. Les indicateurs de conversion et leurs significations sont : d, i L'argument int est converti en un chiffre decimal signe. La precision, si elle est mentionnee, correspond au nombre minimal de chiffres qui doivent apparaitre. Si la conversion fournit moins de chiffres, le resultat est rempli a gauche avec des zeros. Par defaut la precision vaut 1. Lorsque 0 est converti avec une precision valant 0, la sortie est vide. o, u, x, X L'argument unsigned int est converti en un chiffre octal non signe (o), un chiffre decimal non signe (u) ou un chiffre hexadecimal non signe (x et X). Les lettres abcdef sont utilisees pour les conversions avec x, les lettres ABCDEF sont utilisees pour les conversions avec X. La precision, si elle est indiquee, donne un nombre minimal de chiffres a faire apparaitre. Si la valeur convertie necessite moins de chiffres, elle est completee a gauche avec des zeros. La precision par defaut vaut 1. Lorsque 0 est converti avec une precision valant 0, la sortie est vide. e, E L'argument, de type double, est arrondi et presente avec la notation scientifique [-]c.ccce+-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 decimales egal a la precision demandee. Si la precision n'est pas indiquee, l'affichage contiendra 6 decimales. Si la precision vaut zero, il n'y a pas de point decimal. Une conversion E utilise la lettre E (plutot que e) pour introduire l'exposant. Celui-ci contient toujours au moins deux chiffres. Si la valeur affichee est nulle, son exposant est 00. f, F L'argument, de type double, est arrondi et presente avec la notation classique [-]ccc.ccc, ou le nombre de decimales est egal a la precision reclamee. Si la precision n'est pas indiquee, l'affichage se fera avec 6 decimales. Si la precision vaut zero, aucun point n'est affiche. Lorsque le point est affiche, il y a toujours au moins un chiffre devant. SUSv2 ne mentionne pas F et dit qu'une representation des chaines de caracteres pour l'infini ou NaN devrait etre disponible. SUSv3 ajoute l'indicateur F. La norme C99 precise << [-]inf >> ou << [-]infinity >> pour les infinis, et une chaine commencant par << nan >> pour NaN dans le cas d'une conversion f, et les chaines << [-]INF >>, << [-]INFINITY >> ou << NAN* >> pour une conversion F. g, G L'argument, de type double, est converti en style f ou e (F ou E pour la conversion G). La precision indique le nombre de decimales significatives. Si la precision est absente, une valeur par defaut de 6 est utilisee. Si la precision vaut 0, elle est consideree comme valant 1. La notation scientifique e est utilisee si l'exposant est inferieur a -4 ou superieur ou egal a la precision demandee. Les zeros en fin de partie decimale sont supprimes. Un point decimal n'est affiche que s'il est suivi d'au moins un chiffre. a, A (C99; not in SUSv2, but added in SUSv3) For a conversion, the double argument is converted to hexadecimal notation (using the letters abcdef) in the style [-]0xh.hhhhp+-d; for A conversion the prefix 0X, the letters ABCDEF, and the exponent separator P is used. There is one hexadecimal digit before the radix point, and the number of digits after it is equal to the precision. The default precision suffices for an exact representation of the value if an exact representation in base 2 exists and otherwise is sufficiently large to distinguish values of type double. The digit before the radix point is unspecified for nonnormalized numbers, and nonzero but otherwise unspecified for normalized numbers. The exponent, d, is the appropriate exponent of 2 expressed as a decimal integer; it always contains at least one digit; if the value is zero, the exponent is 0. c S'il n'y a pas de modificateur l, l'argument, de type int, est converti en un unsigned char et le caractere correspondant est affiche. Si un modificateur l est present, l'argument de type wint_t (caractere large) est converti en sequence multioctet par un appel a wcrtomb(3), avec un etat de conversion debutant dans l'etat initial. La chaine multioctet resultante est ecrite. s If no l modifier is present: the const char * argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte ('\0'); if a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. Si un modificateur l est present, l'argument de type const wchar_t * est suppose etre un pointeur sur un tableau de caracteres larges. Les caracteres larges du tableau sont convertis en une sequence de caracteres multioctets (chacun par un appel de wcrtomb(3), avec un etat de conversion dans l'etat initial avant le premier caractere large), cela jusqu'au caractere large NULL final compris. Les caracteres multioctets resultants sont ecrits jusqu'a l'octet NULL final (non compris). Si une precision est fournie, il n'y a pas plus d'octets ecrits que la precision indiquee, mais aucun caractere multioctet n'est ecrit partiellement. Remarquez que la precision concerne le nombre d'octets ecrits et non pas le nombre de caracteres larges ou de positions d'ecran. Le tableau doit contenir un caractere large NULL final, sauf si une precision est indiquee et qu'il est suffisamment petit pour que le nombre d'octets ecrits le remplisse avant la fin du tableau. C (Ni dans C99, ni dans C11, mais dans SUSv2, SUSv3 et SUSv4). Synonyme de lc. Ne pas utiliser. S (Ni dans C99, ni dans C11, mais dans SUSv2, SUSv3 et SUSv4). Synonyme de ls. Ne pas utiliser. p L'argument pointeur, du type void * est affiche en hexadecimal, comme avec %#x ou %#lx. n Le nombre de caracteres ecrits jusqu'a present est stocke dans l'entier pointe par l'argument correspondant. Cet argument doit etre un int * 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 bibliotheque C Bionic). Le comportement n'est pas defini si la specification de conversion comporte un drapeau, une longueur de champ ou une precision. m (glibc extension; supported by uClibc and musl, and on Android from API level 29.) Print output of strerror(errno) (or strerrorname_np(errno) in the alternate form). No argument is required. % Un caractere << % >> est ecrit. Il n'y a pas de conversion. L'indicateur complet est << %% >>. VALEUR RENVOYEE En cas de succes, ces fonctions renvoient le nombre d'octets affiches (sans compter l'octet NULL final utilise pour terminer les sorties dans les chaines). 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. ERREURS See write(2) and putwc(3). In addition, the following error may occur: EOVERFLOW The value to be returned is greater than INT_MAX. The dprintf() function may fail additionally if: EBADF The fd argument is not a valid file descriptor. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +--------------------------+--------------------------+----------------+ |Interface | Attribut | Valeur | +--------------------------+--------------------------+----------------+ |printf(), fprintf(), | Securite des threads | MT-Safe locale | |sprintf(), snprintf(), | | | |vprintf(), vfprintf(), | | | |vsprintf(), vsnprintf() | | | +--------------------------+--------------------------+----------------+ STANDARDS fprintf() printf() sprintf() vprintf() vfprintf() vsprintf() snprintf() vsnprintf() C11, POSIX.1-2008. dprintf() vdprintf() GNU, POSIX.1-2008. HISTORIQUE fprintf() printf() sprintf() vprintf() vfprintf() vsprintf() C89, POSIX.1-2001. snprintf() vsnprintf() SUSv2, C99, POSIX.1-2001. En ce qui concerne la valeur de retour de snprintf(), SUSv2 et C99 sont en contradiction : lorsque snprintf() est appelee avec un argument taille=0, SUSv2 precise une valeur de retour indeterminee, inferieure a 1, alors que C99 autorise chaine a etre NULL dans ce cas, et renvoie (comme toujours) le nombre de caracteres qui auraient ete ecrits si la chaine de sortie avait ete assez grande. Les specifications de snprintf() dans POSIX.1-2001 et ses versions superieures sont alignees avec C99. dprintf() vdprintf() GNU, POSIX.1-2008. Issue 4 of the X/Open Portability Guide (SUSv1, 1994) adds '. La bibliotheque glibc 2.1 ajoute les modificateurs de longueur hh, j, t et z et les caracteres de conversion a et A. La bibliotheque glibc 2.2 ajoute le caractere de conversion F avec la semantique C99 et le caractere d'attribut I. glibc 2.35 donne une signification a la forme alternative (#) du specificateur de conversion m, c'est-a-dire %#m. AVERTISSEMENTS Certains programmes reposent imprudemment sur du code comme : sprintf(buf, "%s texte supplementaire", buf); pour ajouter du texte a buf. Cependant, les normes indiquent explicitement que le resultat n'est pas defini si les tampons de source et de destination se recouvrent lors d'un appel a sprintf(), snprintf(), vsprintf() et vsnprintf(). En fonction de la version de gcc(1) utilisee et des options de compilation, ces appels ne produiront pas le resultat attendu. L'implementation des fonctions snprintf() et vsnprintf() de la glibc se conforme a la norme C99 et se comporte comme decrit plus haut depuis la glibc 2.1. Jusqu'a la glibc 2.0.6, elles renvoyaient -1 si la sortie avait ete tronquee. BOGUES Comme sprintf() et vsprintf() supposent des chaines de longueur arbitraire, le programme appelant doit s'assurer de ne pas deborder l'espace d'adressage. C'est souvent difficile. Notez que la taille des chaines peut varier avec la localisation et etre difficilement previsible. Il faut alors utiliser snprintf() ou vsnprintf() a la place (ou encore asprintf(3) et vasprintf(3)). Un code tel que printf(toto); indique souvent un bogue, car toto peut contenir un caractere << % >>. Si toto vient d'une saisie non securisee, il peut contenir %n, ce qui autorise printf() a ecrire dans la memoire, et cree une faille de securite. EXEMPLES Pour afficher Pi avec cinq decimales : #include #include fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0)); Pour afficher une date et une heure sous la forme << Sunday, July 3, 23:15 >>, ou jour_semaine et mois sont des pointeurs sur des chaines : #include fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", weekday, month, day, hour, min); De nombreux pays utilisent un format de date different, comme jour-mois-annee. Une version internationale doit donc etre capable d'afficher les arguments dans l'ordre indique par le format : #include fprintf(stdout, format, jour_semaine, mois, jour, heure, min); ou le format depend de la localisation et peut permuter les arguments. Avec la valeur : "%1$s, %3$d. %2$s, %4$d:%5$.2d\n" On peut obtenir << Dimanche, 3 juillet, 23:15 >>. Pour allouer une chaine de taille suffisante et ecrire dedans (code correct aussi bien pour la glibc 2.0 que pour la glibc 2.1) : #include #include #include 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 traite comme une erreur au lieu d'etre traite de facon elegante. VOIR AUSSI printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Frederic Hantrais , Gregoire Scano et Jean-Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.15 19 juillet 2025 printf(3)