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: db36e9f09e6125e8b5a5fe263c788f32b55cb1ce $
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: db36e9f09e6125e8b5a5fe263c788f32b55cb1ce $")
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_IO_WOULD_BLOCK, //!< IO would block
50
51 FR_BIO_ERROR_IO, //!< IO error - check errno
52 FR_BIO_ERROR_GENERIC, //!< generic "failed" error - check fr_strerror()
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_callback_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
140/** Read raw data from a bio
141 *
142 * @param bio the binary IO handler
143 * @param packet_ctx packet-specific data associated with the buffer
144 * @param buffer where to read the data
145 * @param size amount of data to read.
146 * @return
147 * - <0 for error. The return code will be fr_bio_error(ERROR_NAME)
148 * - 0 for "did not read any data". EOF is a separate signal.
149 */
150static inline ssize_t CC_HINT(nonnull(1,3)) fr_bio_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
151{
152 if (size == 0) return 0;
153
154 /*
155 * We cannot read from the middle of a chain.
156 */
157 fr_assert(!fr_bio_prev(bio));
158
159 return bio->read(bio, packet_ctx, buffer, size);
160}
161
162/** Write raw data to a bio
163 *
164 * @param bio the binary IO handler
165 * @param packet_ctx packet-specific data associated with the buffer
166 * @param buffer the data to write. If NULL, will "flush" any pending data.
167 * @param size amount of data to write. For flush, it should be SIZE_MAX
168 * @return
169 * - <0 for error. The return code will be fr_bio_error(ERROR_NAME)
170 * - 0 for "did not write any data"
171 * - >0 for amount of data written. Should always be equal to size!
172 */
173static inline ssize_t CC_HINT(nonnull(1)) fr_bio_write(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
174{
175 if (size == 0) return 0;
176
177 /*
178 * We cannot write to the middle of a chain.
179 */
180 fr_assert(!fr_bio_prev(bio));
181
182 return bio->write(bio, packet_ctx, buffer, size);
183}
184
186
187#ifndef NDEBUG
188int fr_bio_destructor(fr_bio_t *bio) CC_HINT(nonnull);
189#else
190#define fr_bio_destructor (NULL)
191#endif
192
193#define fr_bio_error(_x) (-(FR_BIO_ERROR_ ## _x))
194
195int fr_bio_shutdown(fr_bio_t *bio) CC_HINT(nonnull);
196
197int fr_bio_free(fr_bio_t *bio) CC_HINT(nonnull);
198
199char const *fr_bio_strerror(ssize_t error);
200
201void fr_bio_cb_set(fr_bio_t *bio, fr_bio_cb_funcs_t const *cb) CC_HINT(nonnull(1));
202
203#undef _CONST
static int const char char buffer[256]
Definition acutest.h:576
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
int fr_bio_free(fr_bio_t *bio)
Free this bio, and everything it calls.
Definition base.c:105
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:173
void fr_bio_cb_set(fr_bio_t *bio, fr_bio_cb_funcs_t const *cb))
Definition base.c:239
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
char const * fr_bio_strerror(ssize_t error)
Definition base.c:207
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:150
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
generic "failed" error - check fr_strerror()
Definition base.h:52
@ FR_BIO_ERROR_IO
IO error - check errno.
Definition base.h:51
@ 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:49
@ FR_BIO_ERROR_BUFFER_TOO_SMALL
the output buffer is too small for the data
Definition base.h:56
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
fr_bio_callback_t shutdown
called when the BIO is being shut down
Definition base.h:90
#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:196
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:34
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:151
#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))