1 #ifndef INCLUDED_ircd_snprintf_h
2 #define INCLUDED_ircd_snprintf_h
4 * IRC - Internet Relay Chat, include/ircd_snprintf.h
5 * Copyright (C) 2000 Kevin L. Mitchell <klmitch@mit.edu>
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2, or (at your option)
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23 #ifndef INCLUDED_config_h
26 #ifndef INCLUDED_sys_types_h
27 #include <sys/types.h>
28 #define INCLUDED_sys_types_h
30 #ifndef INCLUDED_stdarg_h
32 #define INCLUDED_stdarg_h
37 /* structure passed as argument for %v conversion */
39 size_t vd_chars; /* number of characters inserted */
40 size_t vd_overflow; /* number of characters that couldn't be */
41 const char *vd_format; /* format string */
42 va_list vd_args; /* arguments for %v */
45 extern int ircd_snprintf(struct Client *dest, char *buf, size_t buf_len,
46 const char *format, ...);
47 extern int ircd_vsnprintf(struct Client *dest, char *buf, size_t buf_len,
48 const char *format, va_list args);
53 ** These functions are intended to be a complete replacement for
54 ** sprintf and sprintf_irc. They are a (nearly) complete
55 ** reimplementation, and of course they're snprintf clones, making it
56 ** more difficult for accidental buffer overflows to crop up.
58 ** First off, what's missing? These functions support all ANSI C
59 ** conversion specifiers and selected ones from ISO 9x, with the
60 ** exception of all floating-point conversions. The floating-point
61 ** conversions are tricky, and will likely be dependent on the
62 ** representation of a floating-point number on a particular
63 ** architecture. While that representation is likely to conform to
64 ** some standard, it is not currently used in ircu, so seemed like a
65 ** good thing to omit, given the difficulty of implementing it.
67 ** There are two more things missing from this implementation that
68 ** would be required by ANSI; the first is support for multibyte
69 ** character strings, and the second is support for locales, neither
70 ** of which have any relevance for ircu, so again omission seemed to
71 ** be a good policy. Additionally, %#x always causes '0x' (or '0X')
72 ** to be printed, even if the number is zero.
74 ** These functions also have some extensions not seen in a
75 ** standards-compliant implementation; technically, the ISO 9x
76 ** extensions fall into this category, for instance. The ISO 9x
77 ** extensions supported are type extensions--%ju, %tu, and %zu, for
78 ** instance; %qu and %hhu are also supported. The extensions added
79 ** for use in ircu are %Tu, which takes a time_t, and the new %C
80 ** conversion, which inserts either a numeric or a nick, dependant on
81 ** the <dest> parameter. The GNU %m extension, which inserts the
82 ** strerror() string corresponding to the current value of errno, is
83 ** also supported, as is a special %v extension, which essentially
84 ** does a recursive call to ircd_snprintf.
86 ** The following description is descended from the Linux manpage for
87 ** the printf family of functions.
89 ** The format string is composed of zero or more directives:
90 ** ordinary characters (not %), which are copied unchanged to the
91 ** output stream; and conversion specifications, each of which results
92 ** in fetching zero or more subsequent arguments. Each conversion
93 ** specification is introduced by the character %. The arguments must
94 ** correspond properly (after type promotion) with the conversion
95 ** specifier. After the %, the following appear in sequence:
97 ** * Zero or more of the following flags:
99 ** # specifying that the value should be converted to an
100 ** "alternate form." For c, d, i, n, p, s, and u conversions,
101 ** this option has no effect. For o conversions, the precision
102 ** of the number is increased to force the first character of the
103 ** output string to a zero (except if a zero value is printed
104 ** with an explicit precision of zero). For x and X conversions,
105 ** the string '0x' (or '0X' for X conversions) is prepended to
106 ** it. For e, E, f, g, and G conversions, the result will always
107 ** contain a decimal point, even if no digits follow it
108 ** (normally, a decimal point appears in the results of those
109 ** conversions only if a digit follows). For g and G
110 ** conversions, trailing zeros are not removed from the result as
111 ** they would otherwise be. For C conversions, if the
112 ** destination is local and the origin is a user, the
113 ** nick!user@host form is used.
115 ** 0 specifying zero padding. For all conversions except n, the
116 ** converted value is padded on the left with zeros rather than
117 ** blanks. If a precision is given with a numeric conversion (d,
118 ** i, o, u, i, x, and X), the 0 flag is ignored.
120 ** - (a negative field width flag) indicates the converted value is
121 ** to be left adjusted on the field boundary. Except for n
122 ** conversions, the converted value is padded on the right with
123 ** blanks, rather than on the left with blanks or zeros. A -
124 ** overrides a 0 if both are given.
126 ** ' ' (a space) specifying that a blank should be left before a
127 ** positive number produced by a signed conversion (d, e, E, f,
130 ** + specifying that a sign always be placed before a number
131 ** produced by a signed conversion. A + overrides a space if
134 ** : specifying that a struct Client name should be preceded by a
135 ** ':' character if the destination is a user
137 ** * An optional decimal digit string specifying a minimum field
138 ** width. If the converted value has fewer characters than the
139 ** field width, it will be padded with spaces on the left (or right,
140 ** if the left-adjustment flag has been given) to fill out the field
143 ** * An optional precision, in the form of a period (`.') followed by
144 ** an optional digit string. If the digit string is omitted, the
145 ** precision is taken as zero. This gives the minimum number of
146 ** digits to appear for d, i, o, u, x, and X conversions, the number
147 ** of digits to appear after the decimal-point for e, E, and f
148 ** conversions, the maximum number of significant digits for g and G
149 ** conversions, or the maximum number of characters to be printed
150 ** from a string for s conversions.
152 ** * The optional character h, specifying that a following d, i, o, u,
153 ** x, or X conversion corresponds to a short int or unsigned short
154 ** int argument, or that a following n conversion corresponds to a
155 ** pointer to a short int argument. If the h character is given
156 ** again, char is used instead of short int.
158 ** * The optional character l (ell) specifying that a following d, i,
159 ** o, u, x, or X conversion applies to a pointer to a long int or
160 ** unsigned long int argument, or that a following n conversion
161 ** corresponds to a pointer to a long int argument.
163 ** * The character L specifying that a following e, E, f, g, or G
164 ** conversion corresponds to a long double argument, or a following
165 ** d, i, o, u, x, or X conversion corresponds to a long long
166 ** argument. Note that long long is not specified in ANSI C and
167 ** therefore not portable to all architectures.
169 ** * The optional character q. This is equivalent to L.
171 ** * A j character specifying that the following integer (d, i, o, u,
172 ** x, or X) conversion corresponds to an intmax_t argument.
174 ** * A t character specifying that the following integer (d, i, o, u,
175 ** x, or X) conversion corresponds to a ptrdiff_t argument.
177 ** * A z character specifying that the following integer (d, i, o, u,
178 ** x, or X) conversion corresponds to a size_t argument.
180 ** * A T character specifying that the following integer (d, i, o, u,
181 ** x, or X) conversion corresponds to a time_t argument.
183 ** * A character that specifies the type of conversion to be applied.
185 ** A field width or precision, or both, may be indicated by an
186 ** asterisk `*' instead of a digit string. In this case, an int
187 ** argument supplies the field width or precision. A negative field
188 ** width is treated as a left adjustment flag followed by a positive
189 ** field width; a negative precision is treated as though it were
192 ** The conversion specifiers and their meanings are:
194 ** diouxX The int (or appropriate variant) argument is converted
195 ** to signed decimal (d and i), unsigned octal (o),
196 ** unsigned decimal (u), or unsigned hexadecimal (x and
197 ** X) notation. The letters abcdef are used for x
198 ** conversions; the letters ABCDEF are used for X
199 ** conversions. The precision, if any, gives the minimum
200 ** number of digits that must appear; if the converted
201 ** value requires fewer digits, it is padded on the left
204 ** eE [NOT IMPLEMENTED] The double argument is rounded and
205 ** converted in the style [-]d.dddedd where there is one
206 ** digit before the decimal-point character and the
207 ** number of digits after it is equal to the precision;
208 ** if the precision is missing, it is taken as 6; if the
209 ** precision is zero, no decimal-point character appears.
210 ** An E conversion uses the letter E (rather than e) to
211 ** introduce the exponent. The exponent always contains
212 ** at least two digits; if the value is zero, the
215 ** f [NOT IMPLEMENTED] The double argument is rounded and
216 ** converted to decimal notation in the style
217 ** [-]ddd.ddd, where the number of digits after the
218 ** decimal-point character is equal to the precision
219 ** specification. If the precision is missing, it is
220 ** taken as 6; if the precision is explicitly zero, no
221 ** decimal-point character appears. If a decimal point
222 ** appears, at least one digit appears before it.
224 ** g [NOT IMPLEMENTED] The double argument is converted in
225 ** style f or e (or E for G conversions). The precision
226 ** specifies the number of significant digits. If the
227 ** precision is missing, 6 digits are given; if the
228 ** precision is zero, it is treated as 1. Style e is
229 ** used if the exponent from its conversion is less than
230 ** -4 or greater than or equal to the precision.
231 ** Trailing zeros are removed from the fractional part of
232 ** the result; a decimal point appears only if it is
233 ** followed by at least one digit.
235 ** c The int argument is converted to an unsigned char, and
236 ** the resulting character is written.
238 ** s The "char *" argument is expected to be a pointer to
239 ** an array of character type (pointer to a string).
240 ** Characters from the array are written up to (but not
241 ** including) a terminating NUL character; if a precision
242 ** is specified, no more than the number specified are
243 ** written. If a precision is given, no null character
244 ** need be present; if the precision is not specified, or
245 ** is greater than the size of the array, the array must
246 ** contain a terminating NUL character.
248 ** p The "void *" pointer argument is printed in
249 ** hexadecimal (as if by %#x or %#lx).
251 ** n The number of characters written so far is stored into
252 ** the integer indicated by the ``int *'' (or variant)
253 ** pointer argument. No argument is converted.
255 ** m The error message associated with the current value of
256 ** errno is printed as if by %s.
258 ** C The client argument identifier is printed under the
259 ** control of the <dest> argument; if <dest> is NULL or
260 ** is a user, the client's name (nickname or server name)
261 ** is printed; otherwise, the client's network numeric is
264 ** H The channel argument identifier (channel name) is
267 ** v The argument given must be a pointer to a struct
268 ** VarData with vd_format and vd_args must be initialized
269 ** appropriately. On return, vd_chars will contain the
270 ** number of characters added to the buffer, and
271 ** vd_overflow will contain the number of characters that
272 ** could not be added due to buffer overflow or due to a
275 ** % A `%' is written. No argument is converted. The
276 ** complete conversion specification is `%%'.
278 ** In no case does a non-existent or small field width cause
279 ** truncation of a field; if the result of a conversion is wider than
280 ** the field width, the field is expanded to contain the conversion
284 #endif /* INCLUDED_ircd_snprintf_h */