1 /* 2 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana 3 * University Research and Technology 4 * Corporation. All rights reserved. 5 * Copyright (c) 2004-2005 The University of Tennessee and The University 6 * of Tennessee Research Foundation. All rights 7 * reserved. 8 * Copyright (c) 2004-2007 High Performance Computing Center Stuttgart, 9 * University of Stuttgart. All rights reserved. 10 * Copyright (c) 2004-2005 The Regents of the University of California. 11 * All rights reserved. 12 * $COPYRIGHT$ 13 * 14 * Additional copyrights may follow 15 * 16 * $HEADER$ 17 */ 18 19 /** @file 20 * 21 * Buffer safe printf functions for portability to archaic platforms. 22 */ 23 24 #ifndef OPAL_PRINTF_H 25 #define OPAL_PRINTF_H 26 27 #include "opal_config.h" 28 29 #include <stdarg.h> 30 #include <stdlib.h> 31 32 BEGIN_C_DECLS 33 34 /** 35 * Writes to a string under the control of a format string 36 * that specifies how subsequent arguments are converted for output. 37 * 38 * @param str Output string buffer 39 * @param size Size of string buffer 40 * @param fmt Output format 41 * @return Length of output string 42 * 43 * At most size-1 characters are printed into the output string (the 44 * size'th character then gets the terminating `\0'); if the return 45 * value is greater than or equal to the size argument, the string was 46 * too short and some of the printed characters were discarded. The 47 * output is always null-terminated. 48 * 49 * Returns the number of characters that would have been printed if 50 * the size were unlimited (again, not including the final `\0'). 51 * 52 * THIS IS A PORTABILITY FEATURE: USE snprintf() in CODE. 53 */ 54 OPAL_DECLSPEC int opal_snprintf(char *str, size_t size, const char *fmt, ...) __opal_attribute_format__(__printf__, 3, 4); 55 56 57 /** 58 * Writes to a string under the control of a format string that 59 * specifies how arguments accessed via the variable-length argument 60 * facilities of stdarg(3) are converted for output. 61 * 62 * @param str Output string buffer 63 * @param size Size of string buffer 64 * @param fmt Output format 65 * @param ap Variable argument list pointer 66 * @return Length of output string 67 * 68 * At most size-1 characters are printed into the output string (the 69 * size'th character then gets the terminating `\0'); if the return 70 * value is greater than or equal to the size argument, the string was 71 * too short and some of the printed characters were discarded. The 72 * output is always null-terminated. 73 * 74 * Returns the number of characters that would have been printed if 75 * the size were unlimited (again, not including the final `\0'). 76 * 77 * THIS IS A PORTABILITY FEATURE: USE vsnprintf() in CODE. 78 */ 79 OPAL_DECLSPEC int opal_vsnprintf(char *str, size_t size, const char *fmt, va_list ap) __opal_attribute_format__(__printf__, 3, 0); 80 81 /** 82 * Allocates and writes to a string under the control of a format 83 * string that specifies how subsequent arguments are converted for 84 * output. 85 * 86 * @param *ptr Pointer to output string buffer 87 * @param fmt Output format 88 * @return Length of output string 89 * 90 * Sets *ptr to be a pointer to a buffer sufficiently large to hold 91 * the formatted string. This pointer should be passed to free(3) to 92 * release the allocated storage when it is no longer needed. If 93 * sufficient space cannot be allocated, asprintf() and vasprintf() 94 * will return -1 and set ret to be a NULL pointer. 95 * 96 * Returns the number of characters printed. 97 * 98 * Unlike opal_snprintf and opal_vsnprintf, opal_asprintf() is always 99 * available and guarantees that *ptr is NULL when the underlying 100 * asprintf fails. The standard does not require *ptr be set to NULL 101 * on error and some implementations (modern Linux) do not guarantee 102 * such behavior. 103 * 104 */ 105 OPAL_DECLSPEC int opal_asprintf(char **ptr, const char *fmt, ...) __opal_attribute_format__(__printf__, 2, 3); 106 107 108 /** 109 * Allocates and writes to a string under the control of a format 110 * string that specifies how arguments accessed via the 111 * variable-length argument facilities of stdarg(3) are converted for 112 * output. 113 * 114 * @param *ptr Pointer to output string buffer 115 * @param fmt Output format 116 * @param ap Variable argument list pointer 117 * @return Length of output string 118 * 119 * Sets *ptr to be a pointer to a buffer sufficiently large to hold 120 * the formatted string. This pointer should be passed to free(3) to 121 * release the allocated storage when it is no longer needed. If 122 * sufficient space cannot be allocated, asprintf() and vasprintf() 123 * will return -1 and set ret to be a NULL pointer. 124 * 125 * Returns the number of characters printed. 126 * 127 * Unlike opal_snprintf and opal_vsnprintf, opal_vasprintf() is always 128 * available and guarantees that *ptr is NULL when the underlying 129 * asprintf fails. The standard does not require *ptr be set to NULL 130 * on error and some implementations (modern Linux) do not guarantee 131 * such behavior. 132 * 133 */ 134 OPAL_DECLSPEC int opal_vasprintf(char **ptr, const char *fmt, va_list ap) __opal_attribute_format__(__printf__, 2, 0); 135 136 137 END_C_DECLS 138 139 #endif /* OPAL_PRINTF_H */ 140