The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Loading...
Searching...
No Matches
base.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16 */
17
18/**
19 * $Id: c5a3134ea59bdaa4e61dafc9b20408c55bc63648 $
20 * @file lib/bio/base.h
21 * @brief Binary IO abstractions.
22 *
23 * Create abstract binary input / output buffers.
24 *
25 * @copyright 2024 Network RADIUS SAS (legal@networkradius.com)
26 */
27RCSIDH(lib_bio_base_h, "$Id: c5a3134ea59bdaa4e61dafc9b20408c55bc63648 $")
28
29#include <freeradius-devel/util/debug.h>
30#include <freeradius-devel/util/dlist.h>
31
32#ifdef NDEBUG
33#define XDEBUG(_x)
34#else
35#define XDEBUG(fmt, ...) fprintf(stderr, fmt, ## __VA_ARGS__)
36#endif
37
38#ifdef _CONST
39# error _CONST can only be defined in the local header
40#endif
41#ifndef _BIO_PRIVATE
42# define _CONST const
43#else
44# define _CONST
45#endif
46
47typedef enum {
49 FR_BIO_ERROR_GENERIC, //!< -1 == generic "failed" error - check fr_strerror()
50 FR_BIO_ERROR_IO_WOULD_BLOCK, //!< IO would block
51
52 FR_BIO_ERROR_IO, //!< IO error - check errno
53 FR_BIO_ERROR_OOM, //!< out of memory
54 FR_BIO_ERROR_VERIFY, //!< some packet verification error
55 FR_BIO_ERROR_BUFFER_FULL, //!< the buffer is full
56 FR_BIO_ERROR_BUFFER_TOO_SMALL, //!< the output buffer is too small for the data
57 FR_BIO_ERROR_SHUTDOWN, //!< the BIO has been shut down
59
60typedef struct fr_bio_s fr_bio_t;
61
62/** Do a raw read from a socket, or other data source
63 *
64 * These functions should be careful about packet_ctx. This handling depends on a number of factors. Note
65 * that the packet_ctx may be NULL!
66 *
67 * Stream sockets will generally ignore packet_ctx.
68 *
69 * Datagram sockets generally write src/dst IP/port to the packet context. This same packet_ctx is then
70 * passed to bio->write(), which can use it to send the data to the correct destination.
71 *
72 * @param bio the binary IO handler
73 * @param packet_ctx where the function can store per-packet information, such as src/dst IP/port for datagram sockets
74 * @param buffer where the function should store data it reads
75 * @param size the maximum amount of data to read.
76 * @return
77 * - <0 for error
78 * - 0 for "no data available". Note that this does NOT mean EOF! It could mean "we do not have a full packet"
79 * - >0 for amount of data which was read.
80 */
81typedef ssize_t (*fr_bio_read_t)(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size);
82typedef ssize_t (*fr_bio_write_t)(fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size);
83
84typedef int (*fr_bio_io_t)(fr_bio_t *bio); /* read / write blocked callbacks */
85
86typedef void (*fr_bio_callback_t)(fr_bio_t *bio); /* connected / shutdown callbacks */
87
88typedef struct {
89 fr_bio_callback_t connected; //!< called when the BIO is ready to be used
90 fr_bio_io_t shutdown; //!< called when the BIO is being shut down
91 fr_bio_callback_t eof; //!< called when the BIO is at EOF
92 fr_bio_callback_t failed; //!< called when the BIO fails
93
95 fr_bio_io_t write_blocked; //!< returns 0 for "couldn't block", 1 for "did block".
96
97 fr_bio_io_t read_resume; //!< "unblocked" is too similar to "blocked"
100
101/** Accept a new connection on a bio
102 *
103 * @param bio the binary IO handler
104 * @param ctx the talloc ctx for the new bio.
105 * @param[out] accepted the accepted bio
106 * @return
107 * - <0 on error
108 * - 0 for "we did nothing, and there is no new bio available"
109 * - 1 for "the accepted bio is available"
110 */
111typedef int (*fr_bio_accept_t)(fr_bio_t *bio, TALLOC_CTX *ctx, fr_bio_t **accepted);
112
113struct fr_bio_s {
114 void *uctx; //!< user ctx, caller can manually set it.
115
116 fr_bio_read_t _CONST read; //!< read from the underlying bio
117 fr_bio_write_t _CONST write; //!< write to the underlying bio
118
119 fr_dlist_t _CONST entry; //!< in the linked list of multiple bios
120};
121
122static inline CC_HINT(nonnull) fr_bio_t *fr_bio_prev(fr_bio_t *bio)
123{
124 fr_dlist_t *prev = bio->entry.prev;
125
126 if (!prev) return NULL;
127
128 return fr_dlist_entry_to_item(offsetof(fr_bio_t, entry), prev);
129}
130
131static inline CC_HINT(nonnull) fr_bio_t *fr_bio_next(fr_bio_t *bio)
132{
133 fr_dlist_t *next = bio->entry.next;
134
135 if (!next) return NULL;
136
137 return fr_dlist_entry_to_item(offsetof(fr_bio_t, entry), next);
138}
139
140static inline CC_HINT(nonnull) fr_bio_t *fr_bio_head(fr_bio_t *bio)
141{
142 fr_bio_t *this, *prev;
143
144 for (this = bio; (prev = fr_bio_prev(this)) != NULL; this = prev) {
145 /* nothing */
146 }
147
148 return this;
149}
150
151/** Read raw data from a bio
152 *
153 * @param bio the binary IO handler
154 * @param packet_ctx packet-specific data associated with the buffer
155 * @param buffer where to read the data
156 * @param size amount of data to read.
157 * @return
158 * - <0 for error. The return code will be fr_bio_error(ERROR_NAME)
159 * - 0 for "did not read any data". EOF is a separate signal.
160 */
161static inline ssize_t CC_HINT(nonnull(1,3)) fr_bio_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
162{
163 if (size == 0) return 0;
164
165 /*
166 * We cannot read from the middle of a chain.
167 */
168 fr_assert(!fr_bio_prev(bio));
169
170 return bio->read(bio, packet_ctx, buffer, size);
171}
172
173/** Write raw data to a bio
174 *
175 * @param bio the binary IO handler
176 * @param packet_ctx packet-specific data associated with the buffer
177 * @param buffer the data to write. If NULL, will "flush" any pending data.
178 * @param size amount of data to write. For flush, it should be SIZE_MAX
179 * @return
180 * - <0 for error. The return code will be fr_bio_error(ERROR_NAME)
181 * - 0 for "did not write any data"
182 * - >0 for amount of data written. Should always be equal to size!
183 */
184static inline ssize_t CC_HINT(nonnull(1)) fr_bio_write(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
185{
186 if (size == 0) return 0;
187
188 /*
189 * We cannot write to the middle of a chain.
190 */
191 fr_assert(!fr_bio_prev(bio));
192
193 return bio->write(bio, packet_ctx, buffer, size);
194}
195
197
199
200#define fr_bio_error(_x) (-(FR_BIO_ERROR_ ## _x))
201
202int fr_bio_shutdown(fr_bio_t *bio) CC_HINT(nonnull);
203
204char const *fr_bio_strerror(ssize_t error);
205
206void fr_bio_cb_set(fr_bio_t *bio, fr_bio_cb_funcs_t const *cb) CC_HINT(nonnull(1));
207
208ssize_t fr_bio_shutdown_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size);
209ssize_t fr_bio_shutdown_write(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size);
210
211#undef _CONST
static int const char char buffer[256]
Definition acutest.h:576
ssize_t fr_bio_shutdown_write(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
fr_bio_write_t _CONST write
write to the underlying bio
Definition base.h:117
static fr_bio_t * fr_bio_prev(fr_bio_t *bio)
Definition base.h:122
fr_bio_read_t _CONST read
read from the underlying bio
Definition base.h:116
int(* fr_bio_accept_t)(fr_bio_t *bio, TALLOC_CTX *ctx, fr_bio_t **accepted)
Accept a new connection on a bio.
Definition base.h:111
fr_dlist_t _CONST entry
in the linked list of multiple bios
Definition base.h:119
static ssize_t fr_bio_write(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
Write raw data to a bio.
Definition base.h:184
void fr_bio_cb_set(fr_bio_t *bio, fr_bio_cb_funcs_t const *cb))
Definition base.c:193
ssize_t(* fr_bio_read_t)(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
Do a raw read from a socket, or other data source.
Definition base.h:81
static fr_bio_t * fr_bio_next(fr_bio_t *bio)
Definition base.h:131
fr_bio_callback_t connected
called when the BIO is ready to be used
Definition base.h:89
static fr_bio_t * fr_bio_head(fr_bio_t *bio)
Definition base.h:140
char const * fr_bio_strerror(ssize_t error)
Definition base.c:161
static ssize_t fr_bio_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
Read raw data from a bio.
Definition base.h:161
int(* fr_bio_io_t)(fr_bio_t *bio)
Definition base.h:84
fr_bio_error_type_t
Definition base.h:47
@ FR_BIO_ERROR_SHUTDOWN
the BIO has been shut down
Definition base.h:57
@ FR_BIO_ERROR_NONE
Definition base.h:48
@ FR_BIO_ERROR_BUFFER_FULL
the buffer is full
Definition base.h:55
@ FR_BIO_ERROR_GENERIC
-1 == generic "failed" error - check fr_strerror()
Definition base.h:49
@ FR_BIO_ERROR_IO
IO error - check errno.
Definition base.h:52
@ FR_BIO_ERROR_OOM
out of memory
Definition base.h:53
@ FR_BIO_ERROR_VERIFY
some packet verification error
Definition base.h:54
@ FR_BIO_ERROR_IO_WOULD_BLOCK
IO would block.
Definition base.h:50
@ FR_BIO_ERROR_BUFFER_TOO_SMALL
the output buffer is too small for the data
Definition base.h:56
fr_bio_io_t shutdown
called when the BIO is being shut down
Definition base.h:90
fr_bio_callback_t eof
called when the BIO is at EOF
Definition base.h:91
ssize_t(* fr_bio_write_t)(fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size)
Definition base.h:82
#define _CONST
Definition base.h:42
fr_bio_io_t read_resume
"unblocked" is too similar to "blocked"
Definition base.h:97
fr_bio_io_t read_blocked
Definition base.h:94
int fr_bio_shutdown_intermediate(fr_bio_t *bio)
Like fr_bio_shutdown(), but can be called by anyone in the chain.
Definition base.c:150
fr_bio_callback_t failed
called when the BIO fails
Definition base.h:92
void * uctx
user ctx, caller can manually set it.
Definition base.h:114
fr_bio_io_t write_blocked
returns 0 for "couldn't block", 1 for "did block".
Definition base.h:95
void(* fr_bio_callback_t)(fr_bio_t *bio)
Definition base.h:86
int fr_bio_destructor(fr_bio_t *bio)
Free this bio.
Definition base.c:35
fr_bio_io_t write_resume
Definition base.h:98
int fr_bio_shutdown(fr_bio_t *bio)
Shut down a set of BIOs.
Definition base.c:98
ssize_t fr_bio_shutdown_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
#define RCSIDH(h, id)
Definition build.h:486
fr_dlist_t * next
Definition dlist.h:43
static void * fr_dlist_entry_to_item(size_t offset, fr_dlist_t const *entry)
Get the item from a fr_dlist_t.
Definition dlist.h:130
fr_dlist_t * prev
Definition dlist.h:42
Entry in a doubly linked list.
Definition dlist.h:41
long int ssize_t
#define fr_assert(_expr)
Definition rad_assert.h:38
int nonnull(2, 5))