src/helper/membuf.h

   1 /***************************************************************************
   2  *   Copyright (C) 2009 By Duane Ellis                                     *
   3  *   openocd@duaneellis.com                                                *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  ***************************************************************************/
  20 #ifndef HELPER_MEMBUF_H
  21 #define HELPER_MEMBUF_H
  22
  23 /** @file
  24  * MEMBUF - an auto-growing string buffer
  25  *
  26  * With OpenOCD often, one must write code that sends text to
  27  * different places.. the historical command_ctx, or JIM output,
  28  * and/or other places.
  29  *
  30  * This is a simple 'string buffer' that auto-grows.
  31  *
  32  * More correctly put, this is a "memory buffer"
  33  * it may contain binary data
  34  *
  35  * Note: Internally the buffer always has a 'null terminator'
  36  */
  37
  38 /* contents of this structure are 'opaque' */
  39 struct membuf;
  40
  41
  42 /** Create a new membuf
  43  * By default the memory buffer has "some non-zero-size"
  44  * (couple hundred bytes, exact amount is opaque)
  45  */
  46 struct membuf *membuf_new(void);
  47
  48 /** delete (destroy) the mem buffer
  49  * @param pBuf - buffer to release
  50  */
  51 void membuf_delete(struct membuf *pBuf);
  52
  53
  54 /** grow/shrink a membuf by specified amount.
  55  * @param pBuf   - the buffer
  56  * @param amount - the amount to grow or shrink by.
  57  *
  58  * Symantics of 'realloc()' return NULL on failure
  59  */
  60 struct membuf *membuf_grow(struct membuf *pBuf, int amount);
  61
  62 /** how long is this buffer (memlen(), strlen())
  63  * @param pBuf - the buffer
  64  *
  65  * @returns: length of current buffer.
  66  */
  67 size_t membuf_len(struct membuf *pBuf);
  68
  69
  70 /** reset an membuf to zero length.
  71  * @param pBuf - buffer to reset
  72  *
  73  * Note this does not 'release' the memory buffer
  74  */
  75 void membuf_reset(struct membuf *pBuf);
  76
  77
  78 /** sprintf() to the string buffer
  79  * @param pBuf - buffer to capture sprintf() data into
  80  * @param fmt  - printf format
  81  *
  82  * Returns 0 on success
  83  * Returns non-zero on failure
  84  */
  85 int membuf_sprintf(struct membuf *pBuf , const char *fmt, ...);
  86
  87 /** vsprintf() to the string buffer
  88  * @param pBuf - buffer to capture sprintf() data into
  89  * @param fmt  - printf format
  90  * @param ap   - va_list for fmt
  91  *
  92  * Returns 0 on success
  93  * Returns non-zero on failure
  94  */
  95 int membuf_vsprintf(struct membuf *pBuf , const char *fmt, va_list ap);
  96
  97 /** Tokenize lines using strtok()
  98  * @param pBuf - buffer to tokenize
  99  * @param delim - delimiter parameter for strtok_r()
 100  * @param pSave - pointer to string context for tokenization
 101  *
 102  * Identical to "strtok()" - pass "pBuff = NULL" on second call
 103  *
 104  * NOTE: This call is <b > destructive</b> to the buffer.
 105  */
 106 const char *membuf_strtok(struct membuf *pBuf, const char *delim, void **pSave);
 107
 108 /** Return pointer to the memory in the buffer
 109  * @param pBuf - buffer
 110  *
 111  * NOTE: Thou shall not modify this pointer, it is <b > CONST</b>
 112  */
 113 const void *membuf_datapointer(struct membuf *pBuf);
 114
 115
 116 /** Append data to the buffer
 117  * @param pBuf  - buffer to append
 118  * @param pData - pointer to data to append
 119  * @param len   - length of data to append
 120  *
 121  * Modified symantics of "memcpy()".  On memory allocation failure
 122  * returns NULL.  On success, returns pointer to orginal membuf.
 123  */
 124 struct membuf *membuf_append(struct membuf *pBuf, const void *pData, size_t len);
 125
 126
 127 /** Append string to the buffer
 128  * @param pBuf  - buffer to append
 129  * @param str   - string to append
 130  *
 131  * Modified symantics of "strcat()".  On memory allocation failure
 132  * returns NULL.  On success, returns pointer to orginal membuf.
 133  */
 134 struct membuf *membuf_strcat(struct membuf *pBuf, const char *str);
 135
 136
 137 #endif