Tor  0.4.3.0-alpha-dev
buffers.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2019, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * \file buffers.h
9  *
10  * \brief Header file for buffers.c.
11  **/
12 
13 #ifndef TOR_BUFFERS_H
14 #define TOR_BUFFERS_H
15 
16 #include "lib/cc/compat_compiler.h"
17 #include "lib/cc/torint.h"
19 
20 #include <stdarg.h>
21 
22 typedef struct buf_t buf_t;
23 
24 buf_t *buf_new(void);
25 buf_t *buf_new_with_capacity(size_t size);
26 size_t buf_get_default_chunk_size(const buf_t *buf);
27 void buf_free_(buf_t *buf);
28 #define buf_free(b) FREE_AND_NULL(buf_t, buf_free_, (b))
29 void buf_clear(buf_t *buf);
30 buf_t *buf_copy(const buf_t *buf);
31 
32 MOCK_DECL(size_t, buf_datalen, (const buf_t *buf));
33 size_t buf_allocation(const buf_t *buf);
34 size_t buf_slack(const buf_t *buf);
35 
36 uint32_t buf_get_oldest_chunk_timestamp(const buf_t *buf, uint32_t now);
37 size_t buf_get_total_allocation(void);
38 
39 int buf_add(buf_t *buf, const char *string, size_t string_len);
40 void buf_add_string(buf_t *buf, const char *string);
41 void buf_add_printf(buf_t *buf, const char *format, ...)
42  CHECK_PRINTF(2, 3);
43 void buf_add_vprintf(buf_t *buf, const char *format, va_list args)
44  CHECK_PRINTF(2, 0);
45 int buf_move_to_buf(buf_t *buf_out, buf_t *buf_in, size_t *buf_flushlen);
46 void buf_move_all(buf_t *buf_out, buf_t *buf_in);
47 void buf_peek(const buf_t *buf, char *string, size_t string_len);
48 void buf_drain(buf_t *buf, size_t n);
49 int buf_get_bytes(buf_t *buf, char *string, size_t string_len);
50 int buf_get_line(buf_t *buf, char *data_out, size_t *data_len);
51 
52 #define PEEK_BUF_STARTSWITH_MAX 16
53 int buf_peek_startswith(const buf_t *buf, const char *cmd);
54 
55 int buf_set_to_copy(buf_t **output,
56  const buf_t *input);
57 
58 void buf_assert_ok(buf_t *buf);
59 
60 int buf_find_string_offset(const buf_t *buf, const char *s, size_t n);
61 void buf_pullup(buf_t *buf, size_t bytes,
62  const char **head_out, size_t *len_out);
63 char *buf_extract(buf_t *buf, size_t *sz_out);
64 
65 #ifdef BUFFERS_PRIVATE
66 #ifdef TOR_UNIT_TESTS
67 buf_t *buf_new_with_data(const char *cp, size_t sz);
68 #endif
69 size_t buf_preferred_chunk_size(size_t target);
70 
71 #define DEBUG_CHUNK_ALLOC
72 /** A single chunk on a buffer. */
73 typedef struct chunk_t {
74  struct chunk_t *next; /**< The next chunk on the buffer. */
75  size_t datalen; /**< The number of bytes stored in this chunk */
76  size_t memlen; /**< The number of usable bytes of storage in <b>mem</b>. */
77 #ifdef DEBUG_CHUNK_ALLOC
78  size_t DBG_alloc;
79 #endif
80  char *data; /**< A pointer to the first byte of data stored in <b>mem</b>. */
81  uint32_t inserted_time; /**< Timestamp when this chunk was inserted. */
82  char mem[FLEXIBLE_ARRAY_MEMBER]; /**< The actual memory used for storage in
83  * this chunk. */
84 } chunk_t;
85 
86 /** Magic value for buf_t.magic, to catch pointer errors. */
87 #define BUFFER_MAGIC 0xB0FFF312u
88 /** A resizeable buffer, optimized for reading and writing. */
89 struct buf_t {
90  uint32_t magic; /**< Magic cookie for debugging: Must be set to
91  * BUFFER_MAGIC. */
92  size_t datalen; /**< How many bytes is this buffer holding right now? */
93  size_t default_chunk_size; /**< Don't allocate any chunks smaller than
94  * this for this buffer. */
95  chunk_t *head; /**< First chunk in the list, or NULL for none. */
96  chunk_t *tail; /**< Last chunk in the list, or NULL for none. */
97 };
98 
99 chunk_t *buf_add_chunk_with_capacity(buf_t *buf, size_t capacity, int capped);
100 /** If a read onto the end of a chunk would be smaller than this number, then
101  * just start a new chunk. */
102 #define MIN_READ_LEN 8
103 
104 /** Return the number of bytes that can be written onto <b>chunk</b> without
105  * running out of space. */
106 static inline size_t
107 CHUNK_REMAINING_CAPACITY(const chunk_t *chunk)
108 {
109  return (chunk->mem + chunk->memlen) - (chunk->data + chunk->datalen);
110 }
111 
112 /** Return the next character in <b>chunk</b> onto which data can be appended.
113  * If the chunk is full, this might be off the end of chunk->mem. */
114 static inline char *
115 CHUNK_WRITE_PTR(chunk_t *chunk)
116 {
117  return chunk->data + chunk->datalen;
118 }
119 
120 #endif /* defined(BUFFERS_PRIVATE) */
121 
122 #endif /* !defined(TOR_BUFFERS_H) */
size_t buf_datalen(const buf_t *buf)
Definition: buffers.c:394
void buf_clear(buf_t *buf)
Definition: buffers.c:381
size_t buf_slack(const buf_t *buf)
Definition: buffers.c:414
chunk_t * buf_add_chunk_with_capacity(buf_t *buf, size_t capacity, int capped)
Definition: buffers.c:475
buf_t * buf_new(void)
Definition: buffers.c:365
void buf_peek(const buf_t *buf, char *string, size_t string_len)
Definition: buffers.c:610
Integer definitions used throughout Tor.
void void int buf_move_to_buf(buf_t *buf_out, buf_t *buf_in, size_t *buf_flushlen)
Definition: buffers.c:657
void buf_free_(buf_t *buf)
Definition: buffers.c:424
void buf_drain(buf_t *buf, size_t n)
Definition: buffers.c:330
buf_t * buf_new_with_capacity(size_t size)
Definition: buffers.c:356
void buf_add_vprintf(buf_t *buf, const char *format, va_list args)
Definition: buffers.c:578
Utility macros to handle different features and behavior in different compilers.
int buf_peek_startswith(const buf_t *buf, const char *cmd)
Definition: buffers.c:827
buf_t * buf_copy(const buf_t *buf)
Definition: buffers.c:453
void buf_move_all(buf_t *buf_out, buf_t *buf_in)
Definition: buffers.c:690
int buf_get_line(buf_t *buf, char *data_out, size_t *data_len)
Definition: buffers.c:867
void buf_pullup(buf_t *buf, size_t bytes, const char **head_out, size_t *len_out)
Definition: buffers.c:211
void buf_add_string(buf_t *buf, const char *string)
Definition: buffers.c:561
int buf_find_string_offset(const buf_t *buf, const char *s, size_t n)
Definition: buffers.c:808
int buf_add(buf_t *buf, const char *string, size_t string_len)
Definition: buffers.c:527
uint32_t buf_get_oldest_chunk_timestamp(const buf_t *buf, uint32_t now)
Definition: buffers.c:506
void buf_add_printf(buf_t *buf, const char *format,...)
Definition: buffers.c:568
int buf_get_bytes(buf_t *buf, char *string, size_t string_len)
Definition: buffers.c:637
char * buf_extract(buf_t *buf, size_t *sz_out)
Definition: buffers.c:592
Macros to implement mocking and selective exposure for the test code.
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
size_t buf_allocation(const buf_t *buf)
Definition: buffers.c:401
void buf_assert_ok(buf_t *buf)
Definition: buffers.c:903
int buf_set_to_copy(buf_t **output, const buf_t *input)
Definition: buffers.c:891
size_t buf_preferred_chunk_size(size_t target)
Definition: buffers.c:189