src/util/pmix_printf.h

0001 /*
0002  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2005 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2007 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2015-2020 Intel, Inc.  All rights reserved.
0013  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0014  * $COPYRIGHT$
0015  *
0016  * Additional copyrights may follow
0017  *
0018  * $HEADER$
0019  */
0020
0021 /** @file
0022  *
0023  * Buffer safe printf functions for portability to archaic platforms.
0024  */
0025
0026 #ifndef PMIX_PRINTF_H
0027 #define PMIX_PRINTF_H
0028
0029 #include "src/include/pmix_config.h"
0030
0031 #include <stdarg.h>
0032 #include <stdlib.h>
0033 #include "pmix_common.h"
0034
0035 BEGIN_C_DECLS
0036
0037 /**
0038  * Writes to a string under the control of a format string
0039  * that specifies how subsequent arguments are converted for output.
0040  *
0041  * @param str   Output string buffer
0042  * @param size  Size of string buffer
0043  * @param fmt   Output format
0044  * @return      Length of output string
0045  *
0046  * At most size-1 characters are printed into the output string (the
0047  * size'th character then gets the terminating `\0'); if the return
0048  * value is greater than or equal to the size argument, the string was
0049  * too short and some of the printed characters were discarded.  The
0050  * output is always null-terminated.
0051  *
0052  * Returns the number of characters that would have been printed if
0053  * the size were unlimited (again, not including the final `\0').
0054  *
0055  * THIS IS A PORTABILITY FEATURE: USE snprintf() in CODE.
0056  */
0057 PMIX_EXPORT int pmix_snprintf(char *str, size_t size, const char *fmt, ...)
0058 __pmix_attribute_format__(__printf__, 3, 4);
0059
0060 /**
0061  * Writes to a string under the control of a format string that
0062  * specifies how arguments accessed via the variable-length argument
0063  * facilities of stdarg(3) are converted for output.
0064  *
0065  * @param str   Output string buffer
0066  * @param size  Size of string buffer
0067  * @param fmt   Output format
0068  * @param ap    Variable argument list pointer
0069  * @return      Length of output string
0070  *
0071  * At most size-1 characters are printed into the output string (the
0072  * size'th character then gets the terminating `\0'); if the return
0073  * value is greater than or equal to the size argument, the string was
0074  * too short and some of the printed characters were discarded.  The
0075  * output is always null-terminated.
0076  *
0077  * Returns the number of characters that would have been printed if
0078  * the size were unlimited (again, not including the final `\0').
0079  *
0080  * THIS IS A PORTABILITY FEATURE: USE vsnprintf() in CODE.
0081  */
0082 PMIX_EXPORT int pmix_vsnprintf(char *str, size_t size, const char *fmt, va_list ap)
0083 __pmix_attribute_format__(__printf__, 3, 0);
0084
0085 /**
0086  * Allocates and writes to a string under the control of a format
0087  * string that specifies how subsequent arguments are converted for
0088  * output.
0089  *
0090  * @param *ptr  Pointer to output string buffer
0091  * @param fmt   Output format
0092  * @return      Length of output string
0093  *
0094  * Sets *ptr to be a pointer to a buffer sufficiently large to hold
0095  * the formatted string.  This pointer should be passed to free(3) to
0096  * release the allocated storage when it is no longer needed.  If
0097  * sufficient space cannot be allocated, asprintf() and vasprintf()
0098  * will return -1 and set ret to be a NULL pointer.
0099  *
0100  * Returns the number of characters printed.
0101  *
0102  * Unlike pmix_snprintf and pmix_vsnprintf, pmix_asprintf() is always
0103  * available and guarantees that *ptr is NULL when the underlying
0104  * asprintf fails.  The standard does not require *ptr be set to NULL
0105  * on error and some implementations (modern Linux) do not guarantee
0106  * such behavior.
0107  *
0108  */
0109 PMIX_EXPORT int pmix_asprintf(char **ptr, const char *fmt, ...)
0110 __pmix_attribute_format__(__printf__, 2, 3);
0111
0112 /**
0113  * Allocates and writes to a string under the control of a format
0114  * string that specifies how arguments accessed via the
0115  * variable-length argument facilities of stdarg(3) are converted for
0116  * output.
0117  *
0118  * @param *ptr  Pointer to output string buffer
0119  * @param fmt   Output format
0120  * @param ap    Variable argument list pointer
0121  * @return      Length of output string
0122  *
0123  * Sets *ptr to be a pointer to a buffer sufficiently large to hold
0124  * the formatted string.  This pointer should be passed to free(3) to
0125  * release the allocated storage when it is no longer needed.  If
0126  * sufficient space cannot be allocated, asprintf() and vasprintf()
0127  * will return -1 and set ret to be a NULL pointer.
0128  *
0129  * Returns the number of characters printed.
0130  *
0131  * Unlike pmix_snprintf and pmix_vsnprintf, pmix_vasprintf() is always
0132  * available and guarantees that *ptr is NULL when the underlying
0133  * asprintf fails.  The standard does not require *ptr be set to NULL
0134  * on error and some implementations (modern Linux) do not guarantee
0135  * such behavior.
0136  *
0137  */
0138 PMIX_EXPORT int pmix_vasprintf(char **ptr, const char *fmt, va_list ap)
0139 __pmix_attribute_format__(__printf__, 2, 0);
0140
0141 END_C_DECLS
0142
0143 #endif /* PMIX_PRINTF_H */