]>
code.delx.au - gnu-emacs/blob - src/doprnt.c
1 /* Output like sprintf to a buffer of specified size.
2 Also takes args differently: pass one pointer to the end
3 of the format string in addition to the format string itself.
4 Copyright (C) 1985, 2001-2012 Free Software Foundation, Inc.
6 This file is part of GNU Emacs.
8 GNU Emacs is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
13 GNU Emacs is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
21 /* If you think about replacing this with some similar standard C function of
22 the printf family (such as vsnprintf), please note that this function
23 supports the following Emacs-specific features:
25 . For %c conversions, it produces a string with the multibyte representation
26 of the (`int') argument, suitable for display in an Emacs buffer.
28 . For %s and %c, when field width is specified (e.g., %25s), it accounts for
29 the display width of each character, according to char-width-table. That
30 is, it does not assume that each character takes one column on display.
32 . If the size of the buffer is not enough to produce the formatted string in
33 its entirety, it makes sure that truncation does not chop the last
34 character in the middle of its multibyte sequence, producing an invalid
37 . It accepts a pointer to the end of the format string, so the format string
38 could include embedded null characters.
40 . It signals an error if the length of the formatted string is about to
41 overflow MOST_POSITIVE_FIXNUM, to avoid producing strings longer than what
44 OTOH, this function supports only a small subset of the standard C formatted
45 output facilities. E.g., %u and %ll are not supported, and precision is
46 ignored %s and %c conversions. (See below for the detailed documentation of
47 what is supported.) However, this is okay, as this function is supposed to
48 be called from `error' and similar functions, and thus does not need to
49 support features beyond those in `Fformat', which is used by `error' on the
52 /* This function supports the following %-sequences in the `format'
55 %s means print a string argument.
56 %S is silently treated as %s, for loose compatibility with `Fformat'.
57 %d means print a `signed int' argument in decimal.
58 %o means print an `unsigned int' argument in octal.
59 %x means print an `unsigned int' argument in hex.
60 %e means print a `double' argument in exponential notation.
61 %f means print a `double' argument in decimal-point notation.
62 %g means print a `double' argument in exponential notation
63 or in decimal-point notation, whichever uses fewer characters.
64 %c means print a `signed int' argument as a single character.
65 %% means produce a literal % character.
67 A %-sequence may contain optional flag, width, and precision specifiers, and
68 a length modifier, as follows:
70 %<flags><width><precision><length>character
72 where flags is [+ -0], width is [0-9]+, precision is .[0-9]+, and length
73 is empty or l or the value of the pD or pI or pMd (sans "d") macros.
74 Also, %% in a format stands for a single % in the output. A % that
75 does not introduce a valid %-sequence causes undefined behavior.
77 The + flag character inserts a + before any positive number, while a space
78 inserts a space before any positive number; these flags only affect %d, %o,
79 %x, %e, %f, and %g sequences. The - and 0 flags affect the width specifier,
80 as described below. For signed numerical arguments only, the ` ' (space)
81 flag causes the result to be prefixed with a space character if it does not
82 start with a sign (+ or -).
84 The l (lower-case letter ell) length modifier is a `long' data type
85 modifier: it is supported for %d, %o, and %x conversions of integral
86 arguments, must immediately precede the conversion specifier, and means that
87 the respective argument is to be treated as `long int' or `unsigned long
88 int'. Similarly, the value of the pD macro means to use ptrdiff_t,
89 the value of the pI macro means to use EMACS_INT or EMACS_UINT, the
90 value of the pMd etc. macros means to use intmax_t or uintmax_t,
91 and the empty length modifier means `int' or `unsigned int'.
93 The width specifier supplies a lower limit for the length of the printed
94 representation. The padding, if any, normally goes on the left, but it goes
95 on the right if the - flag is present. The padding character is normally a
96 space, but (for numerical arguments only) it is 0 if the 0 flag is present.
97 The - flag takes precedence over the 0 flag.
99 For %e, %f, and %g sequences, the number after the "." in the precision
100 specifier says how many decimal places to show; if zero, the decimal point
101 itself is omitted. For %s and %S, the precision specifier is ignored. */
112 /* Since we use the macro CHAR_HEAD_P, we have to include this, but
113 don't have to include others because CHAR_HEAD_P does not contains
115 #include "character.h"
117 /* Generate output from a format-spec FORMAT,
118 terminated at position FORMAT_END.
119 (*FORMAT_END is not part of the format, but must exist and be readable.)
120 Output goes in BUFFER, which has room for BUFSIZE chars.
121 BUFSIZE must be positive. If the output does not fit, truncate it
122 to fit and return BUFSIZE - 1; if this truncates a multibyte
123 sequence, store '\0' into the sequence's first byte.
124 Returns the number of bytes stored into BUFFER, excluding
125 the terminating null byte. Output is always null-terminated.
126 String arguments are passed as C strings.
127 Integers are passed as C integers. */
130 doprnt (char *buffer
, ptrdiff_t bufsize
, const char *format
,
131 const char *format_end
, va_list ap
)
133 const char *fmt
= format
; /* Pointer into format string. */
134 char *bufptr
= buffer
; /* Pointer into output buffer. */
136 /* Use this for sprintf unless we need something really big. */
137 char tembuf
[DBL_MAX_10_EXP
+ 100];
139 /* Size of sprintf_buffer. */
140 ptrdiff_t size_allocated
= sizeof (tembuf
);
142 /* Buffer to use for sprintf. Either tembuf or same as BIG_BUFFER. */
143 char *sprintf_buffer
= tembuf
;
145 /* Buffer we have got with malloc. */
146 char *big_buffer
= NULL
;
150 char fixed_buffer
[20]; /* Default buffer for small formatting. */
153 char charbuf
[MAX_MULTIBYTE_LENGTH
+ 1]; /* Used for %c. */
157 format_end
= format
+ strlen (format
);
159 fmtcpy
= (format_end
- format
< sizeof (fixed_buffer
) - 1
161 : SAFE_ALLOCA (format_end
- format
+ 1));
165 /* Loop until end of format string or buffer full. */
166 while (fmt
< format_end
&& bufsize
> 0)
168 if (*fmt
== '%') /* Check for a '%' character */
170 ptrdiff_t size_bound
= 0;
171 ptrdiff_t width
; /* Columns occupied by STRING on display. */
173 pDlen
= sizeof pD
- 1,
174 pIlen
= sizeof pI
- 1,
175 pMlen
= sizeof pMd
- 2
178 no_modifier
, long_modifier
, pD_modifier
, pI_modifier
, pM_modifier
179 } length_modifier
= no_modifier
;
180 static char const modifier_len
[] = { 0, 1, pDlen
, pIlen
, pMlen
};
181 int maxmlen
= max (max (1, pDlen
), max (pIlen
, pMlen
));
185 /* Copy this one %-spec into fmtcpy. */
188 while (fmt
< format_end
)
191 if ('0' <= *fmt
&& *fmt
<= '9')
193 /* Get an idea of how much space we might need.
194 This might be a field width or a precision; e.g.
195 %1.1000f and %1000.1f both might need 1000+ bytes.
196 Parse the width or precision, checking for overflow. */
197 ptrdiff_t n
= *fmt
- '0';
198 while (fmt
+ 1 < format_end
199 && '0' <= fmt
[1] && fmt
[1] <= '9')
201 /* Avoid ptrdiff_t, size_t, and int overflow, as
202 many sprintfs mishandle widths greater than INT_MAX.
203 This test is simple but slightly conservative: e.g.,
204 (INT_MAX - INT_MAX % 10) is reported as an overflow
205 even when it's not. */
206 if (n
>= min (INT_MAX
, min (PTRDIFF_MAX
, SIZE_MAX
)) / 10)
207 error ("Format width or precision too large");
208 n
= n
* 10 + fmt
[1] - '0';
215 else if (! (*fmt
== '-' || *fmt
== ' ' || *fmt
== '.'
221 /* Check for the length modifiers in textual length order, so
222 that longer modifiers override shorter ones. */
223 for (mlen
= 1; mlen
<= maxmlen
; mlen
++)
225 if (format_end
- fmt
< mlen
)
227 if (mlen
== 1 && *fmt
== 'l')
228 length_modifier
= long_modifier
;
229 if (mlen
== pDlen
&& memcmp (fmt
, pD
, pDlen
) == 0)
230 length_modifier
= pD_modifier
;
231 if (mlen
== pIlen
&& memcmp (fmt
, pI
, pIlen
) == 0)
232 length_modifier
= pI_modifier
;
233 if (mlen
== pMlen
&& memcmp (fmt
, pMd
, pMlen
) == 0)
234 length_modifier
= pM_modifier
;
237 mlen
= modifier_len
[length_modifier
];
238 memcpy (string
, fmt
+ 1, mlen
);
243 /* Make the size bound large enough to handle floating point formats
244 with large numbers. */
245 if (size_bound
> min (PTRDIFF_MAX
, SIZE_MAX
) - DBL_MAX_10_EXP
- 50)
246 error ("Format width or precision too large");
247 size_bound
+= DBL_MAX_10_EXP
+ 50;
249 /* Make sure we have that much. */
250 if (size_bound
> size_allocated
)
254 big_buffer
= xmalloc (size_bound
);
255 sprintf_buffer
= big_buffer
;
256 size_allocated
= size_bound
;
262 error ("Invalid format operation %s", fmtcpy
);
267 switch (length_modifier
)
271 int v
= va_arg (ap
, int);
272 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
277 long v
= va_arg (ap
, long);
278 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
284 ptrdiff_t v
= va_arg (ap
, ptrdiff_t);
285 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
290 EMACS_INT v
= va_arg (ap
, EMACS_INT
);
291 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
296 intmax_t v
= va_arg (ap
, intmax_t);
297 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
301 /* Now copy into final output, truncating as necessary. */
302 string
= sprintf_buffer
;
307 switch (length_modifier
)
311 unsigned v
= va_arg (ap
, unsigned);
312 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
317 unsigned long v
= va_arg (ap
, unsigned long);
318 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
322 goto signed_pD_modifier
;
325 EMACS_UINT v
= va_arg (ap
, EMACS_UINT
);
326 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
331 uintmax_t v
= va_arg (ap
, uintmax_t);
332 tem
= sprintf (sprintf_buffer
, fmtcpy
, v
);
336 /* Now copy into final output, truncating as necessary. */
337 string
= sprintf_buffer
;
344 double d
= va_arg (ap
, double);
345 tem
= sprintf (sprintf_buffer
, fmtcpy
, d
);
346 /* Now copy into final output, truncating as necessary. */
347 string
= sprintf_buffer
;
354 if (fmtcpy
[1] != 's')
355 minlen
= atoi (&fmtcpy
[1]);
356 string
= va_arg (ap
, char *);
357 tem
= strlen (string
);
358 if (STRING_BYTES_BOUND
< tem
)
359 error ("String for %%s or %%S format is too long");
360 width
= strwidth (string
, tem
);
363 /* Copy string into final output, truncating if no room. */
366 /* Coming here means STRING contains ASCII only. */
367 if (STRING_BYTES_BOUND
< tem
)
368 error ("Format width or precision too large");
371 /* We have already calculated:
372 TEM -- length of STRING,
373 WIDTH -- columns occupied by STRING when displayed, and
374 MINLEN -- minimum columns of the output. */
377 while (minlen
> width
&& bufsize
> 0)
387 /* Truncate the string at character boundary. */
392 if (CHAR_HEAD_P (string
[tem
]))
394 if (BYTES_BY_CHAR_HEAD (string
[tem
]) <= bufsize
- tem
)
401 memcpy (bufptr
, string
, tem
);
403 /* Trigger exit from the loop, but make sure we
404 return to the caller a value which will indicate
405 that the buffer was too small. */
410 memcpy (bufptr
, string
, tem
);
415 while (minlen
< - width
&& bufsize
> 0)
427 int chr
= va_arg (ap
, int);
428 tem
= CHAR_STRING (chr
, (unsigned char *) charbuf
);
431 width
= strwidth (string
, tem
);
432 if (fmtcpy
[1] != 'c')
433 minlen
= atoi (&fmtcpy
[1]);
438 fmt
--; /* Drop thru and this % will be treated as normal */
443 /* Just some character; Copy it if the whole multi-byte form
444 fit in the buffer. */
445 char *save_bufptr
= bufptr
;
447 do { *bufptr
++ = *fmt
++; }
448 while (fmt
< format_end
&& --bufsize
> 0 && !CHAR_HEAD_P (*fmt
));
449 if (!CHAR_HEAD_P (*fmt
))
451 /* Truncate, but return value that will signal to caller
452 that the buffer was too small. */
459 /* If we had to malloc something, free it. */
462 *bufptr
= 0; /* Make sure our string ends with a '\0' */
465 return bufptr
- buffer
;
468 /* Format to an unbounded buffer BUF. This is like sprintf, except it
469 is not limited to returning an 'int' so it doesn't have a silly 2
470 GiB limit on typical 64-bit hosts. However, it is limited to the
471 Emacs-style formats that doprnt supports.
473 Return the number of bytes put into BUF, excluding the terminating
476 esprintf (char *buf
, char const *format
, ...)
480 va_start (ap
, format
);
481 nbytes
= doprnt (buf
, TYPE_MAXIMUM (ptrdiff_t), format
, 0, ap
);
486 #if defined HAVE_X_WINDOWS && defined USE_X_TOOLKIT
488 /* Format to buffer *BUF of positive size *BUFSIZE, reallocating *BUF
489 and updating *BUFSIZE if the buffer is too small, and otherwise
490 behaving line esprintf. When reallocating, free *BUF unless it is
491 equal to NONHEAPBUF, and if BUFSIZE_MAX is nonnegative then signal
492 memory exhaustion instead of growing the buffer size past
495 exprintf (char **buf
, ptrdiff_t *bufsize
,
496 char const *nonheapbuf
, ptrdiff_t bufsize_max
,
497 char const *format
, ...)
501 va_start (ap
, format
);
502 nbytes
= evxprintf (buf
, bufsize
, nonheapbuf
, bufsize_max
, format
, ap
);
509 /* Act like exprintf, except take a va_list. */
511 evxprintf (char **buf
, ptrdiff_t *bufsize
,
512 char const *nonheapbuf
, ptrdiff_t bufsize_max
,
513 char const *format
, va_list ap
)
519 va_copy (ap_copy
, ap
);
520 nbytes
= doprnt (*buf
, *bufsize
, format
, 0, ap_copy
);
522 if (nbytes
< *bufsize
- 1)
524 if (*buf
!= nonheapbuf
)
526 *buf
= xpalloc (NULL
, bufsize
, 1, bufsize_max
, 1);