PRINTF(3) | Linux Programmeurs Handleiding | PRINTF(3) |
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - geformateerde uitvoer conversie
#include <stdio.h>
int printf(const char *opmaak, ...); int fprintf(FILE *stroom, const char *opmaak, ...); int dprintf(int fd, const char *opmaak, ...); int sprintf(char *str, const char *opmaak, ...); int snprintf(char *str, size_t grootte, const char *opmaak, ...); #include <stdarg.h>
int vprintf(const char *opmaak, va_list ap); int vfprintf(FILE *stroom, const char *opmaak, va_list ap); int vdprintf(int fd, const char *opmaak, va_list ap); int vsprintf(char *str, const char *opmaak, va_list ap); int vsnprintf(char *str, size_t grootte, const char *opmaak, va_list ap);
snprintf(), vsnprintf():
dprintf(), vdprintf():
De functies in de printf familie produceren uitvoer volgens een opmaak zoals onder beschreven. De functies printf en vprintf schrijven uitvoer naar stdout, de standaard uitvoer stroom; fprintf en vfprintf schrijven uitvoer naar de gegeven uitvoer stroom; sprintf, snprintf, vsprintf en vsnprintf schrijven naar de karakter string str.
De functie dprintf() is hetzelfde als fprintf() behalve dat het uitvoert naar een bestandsbeschrijving, fd, in plaats van naar de stdio stroom.
De functies snprintf() en vsnprintf() schrijven maximaal size bytes (inclusief het afsluitende null byte ('\0')) naar str.
De functies vprintf(), vfprintf(), vdprintf(), vsprintf(), vsnprintf() zijn equivalent aan de functies printf(), fprintf(), dprintf(), sprintf(), snprintf(), respectievelijk, behalve dat ze worden aangeroepen met een va_list in plaats van een variabel aantal argumenten.. Deze functies roepen de macro va_end niet aan. Omdat ze de va_arg macro gebruiken, de waarde van ap is ongedefinieerd na de aanroep. Zie stdarg(3).
Al deze functies schrijven de uitvoer bepaald door een formaat tekenreeks die specificeert hoe achtereenvolgende argumenten (of argumenten benaderd via een argument met variabele lengte faciliteiten van strdarg(3)) worden omgezet voor uitvoer.
C99 en POSIX.1-2001 specificeren dat de resultaten ongedefinieerd zijn als de aanroep van sprintf(), snprintf(), vsprintf(), of vsnprintf() ervoor zou zorgen dat er gekopieerd moet worden tussen overlappende objecten (b.b.., als de uitvoer tekenreeks tabel en een van de gegeven invoer argumenten wijzen naar dezelfde buffer). Zie OPMERKINGEN.
De formatstring is een karakterstring, beginnend en eindigend in zijn initiële "shift state", als die er is. De vormstring bestaat uit nul of meer aanwijzingen: normale karakters (niet %), die onveranderd naar de uitvoer stroom worden gekopiërd; en conversie specificaties, die elk zorgen dat nul of meer opeenvolgende argumentengepakt worden. Elke conversie specificatie wordt begonnen met het karakter %, en eindigt met een "conversie specificatie". Daar tussenin mogen (in deze volgorde) nul of meer vlaggen aanwezig zijn, een optionele minimum veldbreedte, een optionele precisie en een optionele lengte aanpasser.
De argumenten moeten correct overeenkomen (na type promotie) met de conversie specificatie. Standaard worden de argumenten in de gegeven volgorde gebruikt, waarbij elke '*' (zie Veldbreedte en Precisie) en elke conversie specificatie vraagt om het volgende argument (en het is een fout als een onvoldoende aantal argumentenzijn gegeven). Men kan ook expliciet opgeven welk argument genomen zal worden, op elke plaats waar een argument vereist is, door "%m$" te schrijven inplaats van '%' en "*m$" inplaats van '*', waar het decimale hele getal m de positie in de argumenten lijst van het gewenst argument bepaald, genummerd vanaf 1. Dus,
printf("%*d", width, num);
en
printf("%2$*1$d", width, num);
zijn gelijk. De tweede stijl laat herhaaldelijke referenties naar hetzelfde argument toe. De C99 standaard specificeert de '$' stijl niet; die komt van de Single Unix Specification. Als de '$' stijl wordt gebruikt, dan moet die gebruikt worden voor alle conversies die een argument meekrijgen en alle breedte en precisie argumenten. De stijl mag echter gemengd worden met "%%" vormen die geen argument gebruiken. Er mogen geen gaten zitten in de nummering van de argumenten die met '$'; gespecificeerd worden; bijvoorbeeld, alsargumenten 1 en 3 gespecificeerd zijn, dan moet ook argument 2 ergens in de formatstring gespecificeerd zijn.
Voor sommige numerieke conversies wordt een breuk-karakter ("decimale komma") of duizendtallen-scheidingskarakter gebruikt. Het feitelijk gebruikte karakter hangt af van het LC_NUMERIC deel van de "localiteit" (zie setlocale(3)). De POSIX localiteit gebruikt '.' als breuk-karakter, en heeft geen duizendtallen-scheidingskarakter. Dus:
printf("%'.2f", 1234567.89);
resulteert in "1234567.89" in de POSIX localiteit, in "1234567,89" in de nl_NL localiteit, en in "1.234.567,89" in de da_DK localiteit.
Het karakter % wordt gevolgd door nul of meer van de volgende vlaggen:
De vijf vlag tekens hier boven zijn gedefinieerd in de C99 standaard. De Single UNIX Specification specificeert een vlag additioneel teken.
glibc 2.2 voegde nog een vlag teken toe.
Een optionele decimaal cijfer reeks (met het eerste cijfer niet-nul) dat een minimale veldbreedte opgeeft. Als de geconverteerde waarde minder tekens dan de veldbreedte heeft, dan wordt die links aangevuld met spaties (of rechts, als de links-uitlijnen vlag gegeven is). In plaats van een decimale cijfer reeks kan men ook "*" of "*m$" schrijven (voor een decimaal geheel getal m) op aan te geven dat de veldbreedte gegeven is in het volgende argument, of in het m-de argument, respectievelijk, dat van type int moet zijn. Een negatieve veldbreedte wordt gelezen als een '-' vlag, gevolgd door een positieve veldbreedte. In geen geval leidt een niet-bestaande of kleine veldbreedte tot afkappen van een veld; als het resultaat van een conversie breder is dan de veldbreedte, dan wordt het veld breder gemaakt om het resultaat te kunnen bevatten.
Een optionele precisie, in de vorm van een punt ('.') gevolgd door een optionele decimale cijfer reeks. In plaats van een decimale cijfer reeks kan men "*" of "*m$" schrijven (waarbij m een decimaal geheel getal is) om aan te geven dat de precisie gegeven is in respectievelijk het volgende argument of het m-de argument, wat van type int moet zijn. Als de precisie gegeven is als slechts '.', of als de precisie negatief is, dan wordt dit gelezen als nul. Dit bepaalt het minimum aantal cijfers dat voor d, i, o, u, x en X conversies moet komen, het aantal cijfers dat na het radix karakter moet komen voor a, A, e, E, f en F conversies, het maximum aantal significante cijfers voor g en G conversies, of het maximum aantal karakters dat afgedrukt moet worden van een string voor s en S conversies.
Met "integer conversie" wordt hier d, i, o, u, x of X conversie bedoeld.
SUSv3 specificeert alles zoals hierboven, behalve voor die extra toetsen die expliciet gegeven zijn als zijnde niet-standaard uitbreidingen. SUSv2 specificeerde alleen de lengte van de extra toetsen h (in hd, hi, ho, hx, hX, hn) en l (in ld, li, lo, lx, lX, ln, lc, ls) en L (in Le, LE, Lf, Lg, LG).
Zijnde een niet-standaard uitbreiding behandelen de GNU implementaties ll en L als synoniemen, daarom kan men, bijvoorbeeld ll schrijven (als een synoniem voor de aan de standaard voldoende Lg) en Ld (als synoniem voor de aan de standaard voldoende lld. Dit gebruik is niet overdraagbaar.
Een karakter dat aangeeft welk type van conversie moet worden toegepast. De conversie specificatoren en hun betekenis zijn:
Bij succesvolle terugkeer, retourneren deze functie het aantal tekens dat afgedrukt werd (exclusief het NULL byte gebruikt aan het einde van de tekenreeks).
De functies snprintf() en vsnprintf() schrijven niet meer dan size bytes (inclusief het afsluitende NULL byte ('\0'))). Als de uitvoer werd afgekapt vanwege deze limiet, dan is de teruggegeven waarde gelijk aan het aantal tekens (exclusief het afsluitende NULL byte) dat zou zijn geschreven naar de finale tekenreeks als er genoeg plaats zou zijn geweest. Dus, een terugkeer waarde van size of meer betekent dat de uitvoer werd afgekapt. (Zie hieronder bij OPMERKINGEN.)
Als er een uitvoer fout werd vastgesteld, dan wordt een negatieve waarde teruggegeven.
Voor een uitleg van de termen in deze sectie, zie attributes(7).
Interface | Attribuut | Waarde |
printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf() | Thread veiligheid | MT-Safe taalgebied |
fprintf(), printf(), sprintf(), vprintf(), vfprintf(), vsprintf(): POSIX.1-2001, POSIX.1-2008, C89, C99.
snprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.
De dprintf() en vdprintf() functies waren oorspronkelijk GNU uitbreidingen die later zijn gestandaardiseerd in POSIX.1-2008.
Betreffende de uitvoer waarde van snprintf(), zijn SUSv2 en C99 tegengesteld:als snprintf() werd aangeroepen met size=0 dan bepaalt SUSv2 een ongedefinieerde uitvoer waarde kleiner dan 1, terwijl C99 toe staat str NULL te zijn in dit geval, en geeft een uitvoer waarde terug (zoals altijd) als het aantal tekens dat zou zijn geschreven indien de uitvoer tekenreeks groot genoeg zou zijn geweest. POSIX.1-2001 en later pasten hun specificatie van snprintf() aan op C99.
glibc 2.1 voegt lengte aanpassingen hh, j, t, en z en conversie tekens a en A toe.
glibc 2.2 voegt het conversie teken F met C99 semantiek, en het vlag teken I toe.
Sommige programma´s vertrouwen onvoorzichtig op code zoals de volgende
sprintf(buf, "%s some further text", buf);
om tekst aan buf toe te voegen. Hoewel de standaard expliciet zegt dat de resultaten ongedefinieerd zijn als bron een bestemming buffers overlappen bij het aanroepen van sprintf(), snprintf(), vsprintf(), en vsnprintf(). Afhankelijk van de gebruikte versie van gcc(1), en de toegepaste compiler opties, zullen aanroepen als die hierboven niet het verwachtte resultaat opleveren.
De glibc implementatie van de functies snprintf() en vsnprintf() voldoen aan de C99 standaard, dat betekent, gedraagt zich zoals boven beschreven, sinds glibc versie 2.1. Tot glibc 2.0.6, zou dit -1 terug geven als de uitvoer werd afgekapt.
Omdat sprintf() en vsprintf() uitgaan van een arbitrair lange teken reeks, aanroepers moeten voorzichtig zijn de beschikbare ruimte niet te overlopen, hetgeen vaak onmogelijk is te verzekeren. Merk op dat de lengte van geproduceerde de teken reeksen is taalgebied afhankelijk aan moeilijk te voorspellen. Gebruik snprintf() en vsnprintf() in plaats van (of asprintf(3) en vasprintf(3)).
Code zoals printf(foo); duid vaak op een bug, omdat foo een % teken kan bevatten. Als foo afkomstig is van een niet vertrouwde gebruiker invoer kan het %n bevatten, er voor zorgende dat de printf() aanroep naar geheugen schrijft daarbij een veiligheid gat creëert.
Om Pi af te drukken in vijf decimalen:
#include <math.h> #include <stdio.h> fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
Om een datum en tijd in de vorm van "Sunday, July 3, 10:02" af te drukken, waar weekday en month wijzers naar tekenreeksen zijn:
#include <stdio.h> fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
In veel landen wordt de dag-maand-jaar volgorde gebruikt. Daarom moet een geïnternationaliseerde versie de argumenten af kunnen drukken in een volgorde die gespecificeerd wordt door het format:
#include <stdio.h> fprintf(stdout, format,
weekday, month, day, hour, min);
waar format afhangt van taalgebied, en de argumenten zou kunnen permuteren. Met de waarde
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
zou men "Sonntag, 3. Juli, 10:02" kunnen verkrijgen.
Om een voldoende grote string toe te wijzen en ernaar af te drukken (correcte code voor zowel glibc 2.0 als 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;
/* Bepaal benodigde grootte */
va_start(ap, fmt);
n = vsnprintf(p, size, fmt, ap);
va_end(ap);
if (n < 0)
return NULL;
/* Een extra byte voor '\0' */
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; }
Als afbreken optreedt in glibc versies ouder dan 2.0.6, dan wordt dit behandeld als een fout in plaats van dat het elegant wordt afgehandeld.
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)
Deze pagina is onderdeel van release 5.10 van het Linux man-pages-project. Een beschrijving van het project, informatie over het melden van bugs en de nieuwste versie van deze pagina zijn op https://www.kernel.org/doc/man-pages/ te vinden.
De Nederlandse vertaling van deze handleiding is geschreven door Jos Boersema <joshb@xs4all.nl>, Joost van Baal <joostv-manpages-nl-2398@mdcc.cx>, Mario Blättermann <mario.blaettermann@gmail.com> en Luc Castermans <luc.castermans@gmail.com>
Deze vertaling is vrije documentatie; lees de GNU General Public License Version 3 of later over de Copyright-voorwaarden. Er is geen AANSPRAKELIJKHEID.
Indien U fouten in de vertaling van deze handleiding zou vinden, stuur een e-mail naar debian-l10n-dutch@lists.debian.org.
1 november 2020 | GNU |