xref: /PHP-7.0/main/snprintf.h (revision 478f119a)
1 /*
2    +----------------------------------------------------------------------+
3    | PHP Version 7                                                        |
4    +----------------------------------------------------------------------+
5    | Copyright (c) 1997-2017 The PHP Group                                |
6    +----------------------------------------------------------------------+
7    | This source file is subject to version 3.01 of the PHP license,      |
8    | that is bundled with this package in the file LICENSE, and is        |
9    | available through the world-wide-web at the following url:           |
10    | http://www.php.net/license/3_01.txt                                  |
11    | If you did not receive a copy of the PHP license and are unable to   |
12    | obtain it through the world-wide-web, please send a note to          |
13    | license@php.net so we can mail you a copy immediately.               |
14    +----------------------------------------------------------------------+
15    | Author: Stig Sæther Bakken <ssb@php.net>                             |
16    |         Marcus Boerger <helly@php.net>                               |
17    +----------------------------------------------------------------------+
18 */
19 
20 /* $Id$ */
21 
22 /*
23 
24 Comparing: sprintf, snprintf, slprintf, spprintf
25 
26 sprintf  offers the ability to make a lot of failures since it does not know
27          the size of the buffer it uses. Therefore usage of sprintf often
28          results in possible entries for buffer overrun attacks. So please
29          use this version only if you are sure the call is safe. sprintf
30          always terminstes the buffer it writes to.
31 
32 snprintf knows the buffers size and will not write behind it. But you will
33          have to use either a static buffer or allocate a dynamic buffer
34          before being able to call the function. In other words you must
35          be sure that you really know the maximum size of the buffer required.
36          A bad thing is having a big maximum while in most cases you would
37          only need a small buffer. If the size of the resulting string is
38          longer or equal to the buffer size than the buffer is not terminated.
39          The function also returns the number of chars not including the
40          terminating \0 that were needed to fully comply to the print request.
41 
42 slprintf same as snprintf with the difference that it actually returns the
43          length printed not including the terminating \0.
44 
45 spprintf is the dynamical version of snprintf. It allocates the buffer in size
46          as needed and allows a maximum setting as snprintf (turn this feature
47          off by setting max_len to 0). spprintf is a little bit slower than
48          snprintf and offers possible memory leakes if you miss freeing the
49          buffer allocated by the function. Therfore this function should be
50          used where either no maximum is known or the maximum is much bigger
51          than normal size required. spprintf always terminates the buffer.
52 
53 Example:
54 
55  #define MAX 1024              | #define MAX 1024               | #define MAX 1024
56  char buffer[MAX]              | char buffer[MAX]               | char *buffer;
57                                |                                |
58                                |                                | // No need to initialize buffer:
59                                |                                | // spprintf ignores value of buffer
60  sprintf(buffer, "test");      | snprintf(buffer, MAX, "test"); | spprintf(&buffer, MAX, "text");
61                                |                                | if (!buffer)
62                                |                                |   return OUT_OF_MEMORY
63  // sprintf always terminates | // manual termination of       | // spprintf allays terminates buffer
64  // buffer                     | // buffer *IS* required        |
65                                | buffer[MAX-1] = 0;             |
66  action_with_buffer(buffer);   | action_with_buffer(buffer);    | action_with_buffer(buffer);
67                                |                                | efree(buffer);
68 */
69 
70 #ifndef SNPRINTF_H
71 #define SNPRINTF_H
72 
73 typedef int bool_int;
74 
75 typedef enum {
76 	NO = 0, YES = 1
77 } boolean_e;
78 
79 
80 BEGIN_EXTERN_C()
81 PHPAPI int ap_php_slprintf(char *buf, size_t len, const char *format,...);
82 PHPAPI int ap_php_vslprintf(char *buf, size_t len, const char *format, va_list ap);
83 PHPAPI int ap_php_snprintf(char *, size_t, const char *, ...);
84 PHPAPI int ap_php_vsnprintf(char *, size_t, const char *, va_list ap);
85 PHPAPI int ap_php_vasprintf(char **buf, const char *format, va_list ap);
86 PHPAPI int ap_php_asprintf(char **buf, const char *format, ...);
87 PHPAPI int php_sprintf (char* s, const char* format, ...) PHP_ATTRIBUTE_FORMAT(printf, 2, 3);
88 PHPAPI char * php_gcvt(double value, int ndigit, char dec_point, char exponent, char *buf);
89 PHPAPI char * php_conv_fp(register char format, register double num,
90 		 boolean_e add_dp, int precision, char dec_point, bool_int * is_negative, char *buf, size_t *len);
91 
92 END_EXTERN_C()
93 
94 #ifdef slprintf
95 #undef slprintf
96 #endif
97 #define slprintf ap_php_slprintf
98 
99 #ifdef vslprintf
100 #undef vslprintf
101 #endif
102 #define vslprintf ap_php_vslprintf
103 
104 #ifdef snprintf
105 #undef snprintf
106 #endif
107 #define snprintf ap_php_snprintf
108 
109 #ifdef vsnprintf
110 #undef vsnprintf
111 #endif
112 #define vsnprintf ap_php_vsnprintf
113 
114 #ifndef HAVE_VASPRINTF
115 #define vasprintf ap_php_vasprintf
116 #endif
117 
118 #ifndef HAVE_ASPRINTF
119 #define asprintf ap_php_asprintf
120 #endif
121 
122 #ifdef sprintf
123 #undef sprintf
124 #endif
125 #define sprintf php_sprintf
126 
127 typedef enum {
128 	LM_STD = 0,
129 #if SIZEOF_INTMAX_T
130 	LM_INTMAX_T,
131 #endif
132 #if SIZEOF_PTRDIFF_T
133 	LM_PTRDIFF_T,
134 #endif
135 #if SIZEOF_LONG_LONG
136 	LM_LONG_LONG,
137 #endif
138 	LM_SIZE_T,
139 	LM_LONG,
140 	LM_LONG_DOUBLE,
141 	LM_PHP_INT_T
142 } length_modifier_e;
143 
144 #ifdef PHP_WIN32
145 # define WIDE_INT		__int64
146 #elif SIZEOF_LONG_LONG_INT
147 # define WIDE_INT		long long int
148 #elif SIZEOF_LONG_LONG
149 # define WIDE_INT		long long
150 #else
151 # define WIDE_INT		long
152 #endif
153 typedef WIDE_INT wide_int;
154 typedef unsigned WIDE_INT u_wide_int;
155 
156 PHPAPI char * ap_php_conv_10(register wide_int num, register bool_int is_unsigned,
157 	   register bool_int * is_negative, char *buf_end, register size_t *len);
158 
159 PHPAPI char * ap_php_conv_p2(register u_wide_int num, register int nbits,
160 		 char format, char *buf_end, register size_t *len);
161 
162 /* The maximum precision that's allowed for float conversion. Does not include
163  * decimal separator, exponent, sign, terminator. Currently does not affect
164  * the modes e/f, only g/k/H, as those have a different limit enforced at
165  * another level (see NDIG in php_conv_fp()).
166  * Applies to the formatting functions of both spprintf.c and snprintf.c, which
167  * use equally sized buffers of MAX_BUF_SIZE = 512 to hold the result of the
168  * call to php_gcvt().
169  * This should be reasonably smaller than MAX_BUF_SIZE (I think MAX_BUF_SIZE - 9
170  * should be enough, but let's give some more space) */
171 #define FORMAT_CONV_MAX_PRECISION 500
172 
173 #endif /* SNPRINTF_H */
174 
175 /*
176  * Local variables:
177  * tab-width: 4
178  * c-basic-offset: 4
179  * End:
180  */
181