suricata
util-buffer.h
Go to the documentation of this file.
1 /* Copyright (C) 2007-2023 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Anoop Saldanha <anoopsaldanha@gmail.com>
22  */
23 
24 #ifndef SURICATA_UTIL_BUFFER_H
25 #define SURICATA_UTIL_BUFFER_H
26 
27 typedef struct MemBuffer_ {
28  uint32_t size;
29  uint32_t offset;
30  uint8_t buffer[];
32 
33 MemBuffer *MemBufferCreateNew(uint32_t size);
34 int MemBufferExpand(MemBuffer **buffer, uint32_t expand_by);
35 void MemBufferFree(MemBuffer *buffer);
36 
37 /**
38  * \brief Reset the mem buffer.
39  *
40  * \param mem_buffer Pointer to the mem buffer instance.
41  */
42 static inline void MemBufferReset(MemBuffer *b)
43 {
44  b->buffer[0] = 0;
45  b->offset = 0;
46 }
47 
48 /**
49  * \brief Get the MemBuffers underlying buffer.
50  */
51 #define MEMBUFFER_BUFFER(mem_buffer) (mem_buffer)->buffer
52 
53 /**
54  * \brief Get the MemBuffers current offset.
55  */
56 #define MEMBUFFER_OFFSET(mem_buffer) (mem_buffer)->offset
57 
58 /**
59  * \brief Get the MemBuffers current size.
60  */
61 #define MEMBUFFER_SIZE(mem_buffer) (mem_buffer)->size
62 
63 /**
64  * \brief Write a buffer to the file pointer.
65  *
66  * Accepted buffers can contain both printable and non-printable
67  * characters. Printable characters are written in the printable
68  * format and the non-printable chars are written in hex codes
69  * using the |XX| format.
70  *
71  * For example this would be the kind of output in the file -
72  * onetwo|EF|three|ED|five
73  *
74  * \param buffer Pointer to the src MemBuffer instance to write.
75  * \param fp Pointer to the file instance to write to.
76  */
77 void MemBufferPrintToFP(MemBuffer *buffer, FILE *fp);
78 
79 /**
80  * \brief Write a buffer to the file pointer as a printable char string.
81  *
82  * \param b Pointer to the src MemBuffer instance to write.
83  * \param fp Pointer to the file instance to write to.
84  * \retval size_t bytes written by fwrite()
85  */
86 size_t MemBufferPrintToFPAsString(MemBuffer *b, FILE *fp);
87 
88 /**
89  * \brief Write a buffer in hex format.
90  *
91  * \param b Pointer to the src MemBuffer instance to write.
92  * \param fp Pointer to the file instance to write to.
93  */
94 void MemBufferPrintToFPAsHex(MemBuffer *b, FILE *fp);
95 
96 /**
97  * \brief Write a raw buffer to the MemBuffer dst.
98  *
99  * When we say raw buffer it indicates a buffer that need not be
100  * purely a string buffer. It can be a pure string buffer or not or
101  * a mixture of both. Hence we don't accept any format strings.
102  *
103  * If the remaining space on the buffer is lesser than the length of
104  * the buffer to write, it is truncated to fit into the empty space.
105  *
106  * Also after every write a '\0' is appended. This would indicate
107  * that the total available space to write in the buffer is
108  * MemBuffer->size - 1 and not Membuffer->size. The reason we
109  * append the '\0' is for supporting writing pure string buffers
110  * as well, that can later be used by other string handling funcs.
111  *
112  * \param raw_buffer The buffer to write.
113  * \param raw_buffer_len Length of the above buffer.
114  * \retval write_len Bytes written. If less than raw_len, the buffer is full.
115  */
116 uint32_t MemBufferWriteRaw(MemBuffer *dst, const uint8_t *raw, const uint32_t raw_len);
117 
118 /**
119  * \brief Write a string buffer to the Membuffer dst.
120  *
121  * This function takes a format string and arguments for the format
122  * string like sprintf.
123  *
124  * An example usage of this is -
125  * MemBufferWriteString(mem_buffer_instance, \"%d - %s\", 10, \"one\");
126  *
127  * \param dst The dst MemBuffer instance.
128  * \param format The format string.
129  * \param ... Variable arguments.
130  */
131 void MemBufferWriteString(MemBuffer *dst, const char *fmt, ...) ATTR_FMT_PRINTF(2, 3);
132 
133 #endif /* SURICATA_UTIL_BUFFER_H */
MemBuffer_::buffer
uint8_t buffer[]
Definition: util-buffer.h:30
MemBufferWriteString
void MemBufferWriteString(MemBuffer *dst, const char *fmt,...) ATTR_FMT_PRINTF(2
Write a string buffer to the Membuffer dst.
MemBuffer_::offset
uint32_t offset
Definition: util-buffer.h:29
MemBufferPrintToFPAsString
size_t MemBufferPrintToFPAsString(MemBuffer *b, FILE *fp)
Write a buffer to the file pointer as a printable char string.
Definition: util-buffer.c:96
MemBufferPrintToFP
void MemBufferPrintToFP(MemBuffer *buffer, FILE *fp)
Write a buffer to the file pointer.
Definition: util-buffer.c:86
ATTR_FMT_PRINTF
#define ATTR_FMT_PRINTF(x, y)
Definition: suricata-common.h:410
MemBufferPrintToFPAsHex
void MemBufferPrintToFPAsHex(MemBuffer *b, FILE *fp)
Write a buffer in hex format.
Definition: util-buffer.c:101
MemBuffer_
Definition: util-buffer.h:27
MemBufferWriteRaw
uint32_t MemBufferWriteRaw(MemBuffer *dst, const uint8_t *raw, const uint32_t raw_len)
Write a raw buffer to the MemBuffer dst.
Definition: util-buffer.c:110
MemBufferCreateNew
MemBuffer * MemBufferCreateNew(uint32_t size)
Definition: util-buffer.c:32
MemBuffer
struct MemBuffer_ MemBuffer
MemBuffer_::size
uint32_t size
Definition: util-buffer.h:28
MemBufferExpand
int MemBufferExpand(MemBuffer **buffer, uint32_t expand_by)
expand membuffer by size of 'expand_by'
Definition: util-buffer.c:60
dst
uint16_t dst
Definition: app-layer-dnp3.h:4
MemBufferFree
void MemBufferFree(MemBuffer *buffer)
Definition: util-buffer.c:81