vsprintf

NOM

printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - Formatage des sorties

BIBLIOTHÈQUE

Bibliothèque C standard ( libc, -lc)

SYNOPSIS

#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(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(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

DESCRIPTION

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 arguments 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 NOTES.

CHAÎNE DE FORMAT

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 un 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 :

%[$][drapeaux][largeur][.précision][modificateur de longueur]conversion

The arguments must correspond properly (after type promotion) with the conversion specifier. By default, the arguments are used in the order given, where each '*' (see Field width and Precision below) and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). One can also specify explicitly which argument is taken, at each place where an argument is required, by writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting from 1. Thus,

printf("%*d", width, num);

et

printf("%2$*1$d", width, num);

are equivalent. The second style allows repeated references to the same argument. The C99 standard does not include the style using '$', which comes from the Single UNIX Specification. If the style using '$' is used, it must be used throughout for all conversions taking an argument and all width and precision arguments, but it may be mixed with "%%" formats, which do not consume an argument. There may be no gaps in the numbers of arguments specified using '$'; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string. For some numeric conversions a radix character ("decimal point") or thousands' grouping character is used. The actual character used depends on the LC_NUMERIC part of the locale. (See setlocale(3).) The POSIX locale uses '.' as radix character, and does not have a grouping character. Thus,

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.

Caractères d'attribut

Le caractère % peut être éventuellement suivi par zéro ou plusieurs des attributs suivants :

#

The value should be converted to an "alternate form". For o conversions, the first character of the output string is made zero (by prefixing a 0 if it was not zero already). For x and X conversions, a nonzero result has the string "0x" (or "0X" for X conversions) prepended to it. For a, A, e, E, f, F, g, and G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be. For m, if errno contains a valid error code, the output of strerrorname_np(errno) is printed; otherwise, the value stored in errno is printed as a decimal number. For other conversions, the result is undefined.

0

Indique le remplissage avec des zéros. Pour les conversions d, i, o, u, x, X, a, A, e, E, f, F, g et G, la valeur est complétée à gauche par des zéros plutôt que par des espaces. Si les attributs 0 et - apparaissent ensemble, l'attribut 0 est ignoré. Si une précision est fournie avec une conversion numérique ( d, i, o, u, x et X), l'attribut 0 est ignoré. Pour les autres conversions, le comportement est indéfini.

-

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 - surcharge un attribut 0 si les deux sont fournis.

' '

(une espace) Un blanc indique qu'une espace doit être laissée avant un nombre positif (ou une chaîne vide) produit par une conversion signée

+

Un signe (+ ou -) doit toujours être placé 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 + surcharge un attribut « espace » si les deux sont fournis.

Les cinq caractères d'attributs ci-dessus sont définis dans la norme C99, les Spécifications UNIX Single en ajoutent un :

'

For decimal conversion (i, d, u, f, F, g, G) the output is to be grouped with thousands' grouping characters if the locale information indicates any. (See setlocale(3).) Note that many versions of gcc(1) cannot parse this option and will issue a warning. (SUSv2 did not include %'F, but SUSv3 added it.) Note also that the default locale of a C program is "C" whose locale information indicates no thousands' grouping character. Therefore, without a prior call to setlocale(3), no thousands' grouping characters will be printed.

La glibc 2.2 ajoute un caractère d'attribut supplémentaire.

I

Pour les conversions décimales (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.

Précision

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 à d, i, o, u, x ou X.

hh

La conversion d’entier suivante correspond à un signed char ou à un unsigned char, ou la conversion n suivante correspond à un pointeur sur un argument signed char.

h

La conversion d’entier suivante correspond à un short ou à un unsigned short, ou la conversion n suivante correspond à un pointeur sur un argument short.

l

(ell) A following integer conversion corresponds to a long or unsigned long argument, or a following n conversion corresponds to a pointer to a long argument, or a following c conversion corresponds to a wint_t argument, or a following s conversion corresponds to a pointer to wchar_t argument. On a following a, A, e, E, f, F, g, or G conversion, this length modifier is ignored (C99; not in SUSv2).

ll

(lettre l en double). La conversion d’entier suivante correspond à un long long ou à un unsigned long long, ou la conversion n suivante correspond à un pointeur sur un long long.

q

Un synonyme de ll. Il s'agit d'une extension non standard, dérivée de BSD ; évitez son utilisation dans du nouveau code.

L

La conversion a, A, e, E, f, F, g ou G suivante correspond à un argument long double (C99 autorise %LF mais pas SUSv2).

j

La conversion d’entier suivante correspond à un argument intmax_t ou uintmax_t, ou la conversion n suivante correspond à un pointeur sur un argument intmax_t.

z

La conversion d’entier suivante correspond à un argument size_t ou ssize_t, ou la conversion n suivante correspond à un pointeur sur un argument size_t.

Z

Un synonyme non standard de z qui précède l'apparition de z. Ne pas l'utiliser dans du nouveau code.

t

La conversion d’entier suivante correspond à un argument ptrdiff_t, ou la conversion n suivante correspond à un pointeur sur un argument ptrdiff_t.

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.

Indicateurs de conversion

Un caractère indique le type de conversion à apporter. Les indicateurs de conversion et leurs significations sont :

d, i

L'argument int 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  1. Lorsque 0 est converti avec une précision valant  0, la sortie est vide.

o, u, x, X

L'argument unsigned int est converti en un chiffre octal non signé ( o), un chiffre décimal non signé ( u) ou un chiffre hexadécimal non signé ( x et X). Les lettres abcdef sont utilisées pour les conversions avec x, les lettres ABCDEF sont utilisées pour les conversions avec X. 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  1. Lorsque  0 est converti avec une précision valant  0, la sortie est vide.

e, E

L'argument, de type double, est arrondi et présenté 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 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 E utilise la lettre E (plutôt que e) pour introduire l'exposant. Celui-ci contient toujours au moins deux chiffres. Si la valeur affichée est nulle, son exposant est 00.

f, F

L'argument, de type double, est arrondi et présenté avec la notation classique [-]ccc .ccc, 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.

SUSv2 ne mentionne pas F et dit qu'une représentation des chaînes de caractères pour l'infini ou NaN devrait être disponible. SUSv3 ajoute l'indicateur F. 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 f, et les chaînes « [-]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 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  0, elle est considérée comme valant 1. La notation scientifique e 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.

a, A

(C99, pas dans SUSv2, mais rajouté dans SUSv3). Pour la conversion a, l'argument de type double est transformé en notation hexadécimale (avec les lettres abcdef) de forme [-] 0xh.hhhhp±d ; pour la conversion A, le préfixe 0X, les lettres ABCDEF et le séparateur d'exposant P 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 double. 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.

c

S'il n'y a pas de modificateur l, l'argument, de type int, est converti en un unsigned char et le caractère correspondant est affiché. Si un modificateur l est présent, l'argument de type wint_t (caractère large) est converti en séquence multioctet par un appel à wcrtomb(3), avec un état de conversion débutant dans l'état initial. La chaîne multioctet résultante est écrite.

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 présent, l'argument de type const wchar_t * 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 wcrtomb(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' octets écrits et non pas le nombre de caractères larges ou de positions d'écrans. 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.

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 affiché en hexadécimal, comme avec %#x ou %#lx.

n

Le nombre de caractères écrits jusqu'à présent est stocké dans l'entier pointé par l'argument correspondant. Cet argument doit être 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 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.

m

(glibc extension; supported by uClibc and musl.) Print output of strerror(errno) (or strerrorname_np(errno) in the alternate form). No argument is required.

%

A '%' is written. No argument is converted. The complete conversion specification is '%%'.

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). 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 NOTES.) Si une erreur de sortie s'est produite, une valeur négative est renvoyée.

VERSIONS

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 gives a meaning to the alternate form ( #) of the m conversion specifier, that is %#m.

ATTRIBUTS

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

STANDARDS

fprintf(), printf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99. dprintf() et vdprintf() sont originellement des extensions GNU. Elles ont été standardisées dans POSIX.1-2008. En ce qui concerne la valeur de retour de snprintf(), SUSv2 et C99 sont en contradiction : lorsque snprintf() est appelée avec un argument taille=0, SUSv2 précise une valeur de retour indéterminée, inférieure à 1, alors que C99 autorise chaîne à ê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 snprintf() dans POSIX.1-2001 et ses versions supérieures sont alignées avec C99.

NOTES

Certains programmes reposent imprudemment sur du code comme :

sprintf(buf, "%s some further text", 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. The glibc implementation of the functions snprintf() and vsnprintf() conforms to the C99 standard, that is, behaves as described above, since glibc 2.1. Until glibc 2.0.6, they would return -1 when the output was truncated.

BOGUES

Comme sprintf() et vsprintf() 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 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é.

EXEMPLES

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",
        jour_semaine, mois, jour, heure, minute);

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"

On peut obtenir « Dimanche, 3 juillet, 23:15 ». 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;

    /* Déterminer la taille requise. */

    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;
}

If truncation occurs in glibc versions prior to glibc 2.0.6, this is treated as an error instead of being handled gracefully.

VOIR AUSSI

printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <[email protected]>, Thierry Vignaud <[email protected]>, François Micaux, Alain Portal <[email protected]>, Jean-Philippe Guérard <[email protected]>, Jean-Luc Coulon (f5ibh) <[email protected]>, Julien Cristau <[email protected]>, Thomas Huriaux <[email protected]>, Nicolas François <[email protected]>, Florentin Duneau <[email protected]>, Simon Paillard <[email protected]>, Denis Barbier <[email protected]>, David Prévot <[email protected]>, Frédéric Hantrais <[email protected]> et Grégoire Scano <[email protected]> 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 à [email protected]