root/opal/util/printf.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   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 

/* [<][>][^][v][top][bottom][index][help] */