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 (c) 2015-2017 Intel, Inc. All rights reserved. 13 * $COPYRIGHT$ 14 * 15 * Additional copyrights may follow 16 * 17 * $HEADER$ 18 */ 19 20 /** @file 21 * 22 * Buffer safe printf functions for portability to archaic platforms. 23 */ 24 25 #ifndef PMIX_PRINTF_H 26 #define PMIX_PRINTF_H 27 28 #include <src/include/pmix_config.h> 29 #include <pmix_common.h> 30 31 #include <stdarg.h> 32 #include <stdlib.h> 33 34 BEGIN_C_DECLS 35 36 /** 37 * Writes to a string under the control of a format string 38 * that specifies how subsequent arguments are converted for output. 39 * 40 * @param str Output string buffer 41 * @param size Size of string buffer 42 * @param fmt Output format 43 * @return Length of output string 44 * 45 * At most size-1 characters are printed into the output string (the 46 * size'th character then gets the terminating `\0'); if the return 47 * value is greater than or equal to the size argument, the string was 48 * too short and some of the printed characters were discarded. The 49 * output is always null-terminated. 50 * 51 * Returns the number of characters that would have been printed if 52 * the size were unlimited (again, not including the final `\0'). 53 * 54 * THIS IS A PORTABILITY FEATURE: USE snprintf() in CODE. 55 */ 56 PMIX_EXPORT int pmix_snprintf(char *str, size_t size, const char *fmt, ...) __pmix_attribute_format__(__printf__, 3, 4); 57 58 59 /** 60 * Writes to a string under the control of a format string that 61 * specifies how arguments accessed via the variable-length argument 62 * facilities of stdarg(3) are converted for output. 63 * 64 * @param str Output string buffer 65 * @param size Size of string buffer 66 * @param fmt Output format 67 * @param ap Variable argument list pointer 68 * @return Length of output string 69 * 70 * At most size-1 characters are printed into the output string (the 71 * size'th character then gets the terminating `\0'); if the return 72 * value is greater than or equal to the size argument, the string was 73 * too short and some of the printed characters were discarded. The 74 * output is always null-terminated. 75 * 76 * Returns the number of characters that would have been printed if 77 * the size were unlimited (again, not including the final `\0'). 78 * 79 * THIS IS A PORTABILITY FEATURE: USE vsnprintf() in CODE. 80 */ 81 PMIX_EXPORT int pmix_vsnprintf(char *str, size_t size, const char *fmt, va_list ap) __pmix_attribute_format__(__printf__, 3, 0); 82 83 /** 84 * Allocates and writes to a string under the control of a format 85 * string that specifies how subsequent arguments are converted for 86 * output. 87 * 88 * @param *ptr Pointer to output string buffer 89 * @param fmt Output format 90 * @return Length of output string 91 * 92 * Sets *ptr to be a pointer to a buffer sufficiently large to hold 93 * the formatted string. This pointer should be passed to free(3) to 94 * release the allocated storage when it is no longer needed. If 95 * sufficient space cannot be allocated, asprintf() and vasprintf() 96 * will return -1 and set ret to be a NULL pointer. 97 * 98 * Returns the number of characters printed. 99 * 100 * THIS IS A PORTABILITY FEATURE: USE asprintf() in CODE. 101 */ 102 PMIX_EXPORT int pmix_asprintf(char **ptr, const char *fmt, ...) __pmix_attribute_format__(__printf__, 2, 3); 103 104 105 /** 106 * Allocates and writes to a string under the control of a format 107 * string that specifies how arguments accessed via the 108 * variable-length argument facilities of stdarg(3) are converted for 109 * output. 110 * 111 * @param *ptr Pointer to output string buffer 112 * @param fmt Output format 113 * @param ap Variable argument list pointer 114 * @return Length of output string 115 * 116 * Sets *ptr to be a pointer to a buffer sufficiently large to hold 117 * the formatted string. This pointer should be passed to free(3) to 118 * release the allocated storage when it is no longer needed. If 119 * sufficient space cannot be allocated, asprintf() and vasprintf() 120 * will return -1 and set ret to be a NULL pointer. 121 * 122 * Returns the number of characters printed. 123 * 124 * THIS IS A PORTABILITY FEATURE: USE vasprintf() in CODE. 125 */ 126 PMIX_EXPORT int pmix_vasprintf(char **ptr, const char *fmt, va_list ap) __pmix_attribute_format__(__printf__, 2, 0); 127 128 129 END_C_DECLS 130 131 #endif /* PMIX_PRINTF_H */