Annotation of embedaddon/php/main/snprintf.h, revision 1.1.1.5

1.1       misho       1: /*
                      2:    +----------------------------------------------------------------------+
                      3:    | PHP Version 5                                                        |
                      4:    +----------------------------------------------------------------------+
1.1.1.5 ! misho       5:    | Copyright (c) 1997-2014 The PHP Group                                |
1.1       misho       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: 
1.1.1.2   misho      20: /* $Id$ */
1.1       misho      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
1.1.1.4   misho      30:          always terminstes the buffer it writes to.
1.1       misho      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 beeing 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
1.1.1.4   misho      51:          than normal size required. spprintf always terminates the buffer.
1.1       misho      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
1.1.1.4   misho      63:  // sprintf always terminates | // manual termination of       | // spprintf allays terminates buffer
1.1       misho      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, int *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: } length_modifier_e;
                    142: 
                    143: #ifdef PHP_WIN32
                    144: # define WIDE_INT              __int64
                    145: #elif SIZEOF_LONG_LONG_INT
                    146: # define WIDE_INT              long long int
                    147: #elif SIZEOF_LONG_LONG
                    148: # define WIDE_INT              long long
                    149: #else
                    150: # define WIDE_INT              long
                    151: #endif
                    152: typedef WIDE_INT wide_int;
                    153: typedef unsigned WIDE_INT u_wide_int;
                    154: 
                    155: extern char * ap_php_conv_10(register wide_int num, register bool_int is_unsigned,
                    156:           register bool_int * is_negative, char *buf_end, register int *len);
                    157: 
                    158: extern char * ap_php_conv_p2(register u_wide_int num, register int nbits,
                    159:                 char format, char *buf_end, register int *len);
                    160: 
                    161: /* The maximum precision that's allowed for float conversion. Does not include
                    162:  * decimal separator, exponent, sign, terminator. Currently does not affect
                    163:  * the modes e/f, only g/k/H, as those have a different limit enforced at
                    164:  * another level (see NDIG in php_conv_fp()).
                    165:  * Applies to the formatting functions of both spprintf.c and snprintf.c, which
                    166:  * use equally sized buffers of MAX_BUF_SIZE = 512 to hold the result of the
                    167:  * call to php_gcvt().
                    168:  * This should be reasonably smaller than MAX_BUF_SIZE (I think MAX_BUF_SIZE - 9
                    169:  * should be enough, but let's give some more space) */
                    170: #define FORMAT_CONV_MAX_PRECISION 500
                    171: 
                    172: #endif /* SNPRINTF_H */
                    173: 
                    174: /*
                    175:  * Local variables:
                    176:  * tab-width: 4
                    177:  * c-basic-offset: 4
                    178:  * End:
                    179:  */

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>