base.h File Reference

Binary IO abstractions. More...

#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/dlist.h>

Include dependency graph for base.h:

Go to the source code of this file.

Data Structures
struct	fr_bio_cb_funcs_t
struct	fr_bio_s

Macros
#define	_CONST   const
#define	fr_bio_error(_x)   (-(FR_BIO_ERROR_ ## _x))
#define	XDEBUG(fmt, ...)   fprintf(stderr, fmt, ## __VA_ARGS__)

Typedefs
typedef int(*	fr_bio_accept_t) (fr_bio_t *bio, TALLOC_CTX *ctx, fr_bio_t **accepted)
	Accept a new connection on a bio.
typedef void(*	fr_bio_callback_t) (fr_bio_t *bio)
typedef int(*	fr_bio_io_t) (fr_bio_t *bio)
typedef 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.
typedef struct fr_bio_s	fr_bio_t
typedef ssize_t(*	fr_bio_write_t) (fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size)

Enumerations
enum	fr_bio_error_type_t {   FR_BIO_ERROR_NONE = 0 ,   FR_BIO_ERROR_GENERIC ,   FR_BIO_ERROR_IO_WOULD_BLOCK ,   FR_BIO_ERROR_IO ,   FR_BIO_ERROR_OOM ,   FR_BIO_ERROR_VERIFY ,   FR_BIO_ERROR_BUFFER_FULL ,   FR_BIO_ERROR_BUFFER_TOO_SMALL ,   FR_BIO_ERROR_SHUTDOWN }

Functions
void	fr_bio_cb_set (fr_bio_t *bio, fr_bio_cb_funcs_t const *cb))
int	fr_bio_destructor (fr_bio_t *bio)
	Free this bio.
static fr_bio_t *	fr_bio_head (fr_bio_t *bio)
static fr_bio_t *	fr_bio_next (fr_bio_t *bio)
static fr_bio_t *	fr_bio_prev (fr_bio_t *bio)
static ssize_t	fr_bio_read (fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
	Read raw data from a bio.
int	fr_bio_shutdown (fr_bio_t *bio)
	Shut down a set of BIOs.
int	fr_bio_shutdown_intermediate (fr_bio_t *bio)
	Like fr_bio_shutdown(), but can be called by anyone in the chain.
ssize_t	fr_bio_shutdown_read (fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
ssize_t	fr_bio_shutdown_write (fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
char const *	fr_bio_strerror (ssize_t error)
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.

Detailed Description

Binary IO abstractions.

Id

c5a3134ea59bdaa4e61dafc9b20408c55bc63648

Create abstract binary input / output buffers.

Copyright

2024 Network RADIUS SAS (legal.nosp@m.@net.nosp@m.workr.nosp@m.adiu.nosp@m.s.com)

Definition in file base.h.

---

Data Structure Documentation

fr_bio_cb_funcs_t

struct fr_bio_cb_funcs_t

Definition at line 88 of file base.h.

Collaboration diagram for fr_bio_cb_funcs_t:

Data Fields
fr_bio_callback_t	connected	called when the BIO is ready to be used
fr_bio_callback_t	eof	called when the BIO is at EOF
fr_bio_callback_t	failed	called when the BIO fails
fr_bio_io_t	read_blocked
fr_bio_io_t	read_resume	"unblocked" is too similar to "blocked"
fr_bio_io_t	shutdown	called when the BIO is being shut down
fr_bio_io_t	write_blocked	returns 0 for "couldn't block", 1 for "did block".
fr_bio_io_t	write_resume

fr_bio_s

struct fr_bio_s

Definition at line 113 of file base.h.

Collaboration diagram for fr_bio_s:

Data Fields
fr_dlist_t _CONST	entry	in the linked list of multiple bios
fr_bio_read_t _CONST	read	read from the underlying bio
void *	uctx	user ctx, caller can manually set it.
fr_bio_write_t _CONST	write	write to the underlying bio

Macro Definition Documentation

_CONST

#define _CONST   const

Definition at line 42 of file base.h.

fr_bio_error

#define fr_bio_error

(

_x

)

(-(FR_BIO_ERROR_ ## _x))

Definition at line 200 of file base.h.

XDEBUG

#define XDEBUG	(		fmt,
			...
	)		fprintf(stderr, fmt, ## __VA_ARGS__)

Definition at line 35 of file base.h.

Typedef Documentation

fr_bio_accept_t

typedef int(* fr_bio_accept_t) (fr_bio_t *bio, TALLOC_CTX *ctx, fr_bio_t **accepted)

Accept a new connection on a bio.

Parameters

	bio	the binary IO handler
	ctx	the talloc ctx for the new bio.
[out]	accepted	the accepted bio

Returns

• <0 on error
• 0 for "we did nothing, and there is no new bio available"
• 1 for "the accepted bio is available"

Definition at line 111 of file base.h.

fr_bio_callback_t

typedef void(* fr_bio_callback_t) (fr_bio_t *bio)

Definition at line 86 of file base.h.

fr_bio_io_t

typedef int(* fr_bio_io_t) (fr_bio_t *bio)

Definition at line 84 of file base.h.

fr_bio_read_t

typedef 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.

These functions should be careful about packet_ctx. This handling depends on a number of factors. Note that the packet_ctx may be NULL!

Stream sockets will generally ignore packet_ctx.

Datagram sockets generally write src/dst IP/port to the packet context. This same packet_ctx is then passed to bio->write(), which can use it to send the data to the correct destination.

Parameters

bio	the binary IO handler
packet_ctx	where the function can store per-packet information, such as src/dst IP/port for datagram sockets
buffer	where the function should store data it reads
size	the maximum amount of data to read.

Returns

• <0 for error
• 0 for "no data available". Note that this does NOT mean EOF! It could mean "we do not have a full packet"
• >0 for amount of data which was read.

Definition at line 81 of file base.h.

fr_bio_t

typedef struct fr_bio_s fr_bio_t

Definition at line 60 of file base.h.

fr_bio_write_t

typedef ssize_t(* fr_bio_write_t) (fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size)

Definition at line 82 of file base.h.

Enumeration Type Documentation

fr_bio_error_type_t

enum fr_bio_error_type_t

Enumerator
FR_BIO_ERROR_NONE
FR_BIO_ERROR_GENERIC	-1 == generic "failed" error - check fr_strerror()
FR_BIO_ERROR_IO_WOULD_BLOCK	IO would block.
FR_BIO_ERROR_IO	IO error - check errno.
FR_BIO_ERROR_OOM	out of memory
FR_BIO_ERROR_VERIFY	some packet verification error
FR_BIO_ERROR_BUFFER_FULL	the buffer is full
FR_BIO_ERROR_BUFFER_TOO_SMALL	the output buffer is too small for the data
FR_BIO_ERROR_SHUTDOWN	the BIO has been shut down

Definition at line 47 of file base.h.

Function Documentation

fr_bio_cb_set()

void fr_bio_cb_set	(	fr_bio_t *	bio,
		fr_bio_cb_funcs_t const *	cb
	)

Definition at line 193 of file base.c.

Here is the caller graph for this function:

fr_bio_destructor()

int fr_bio_destructor

(

fr_bio_t *

bio

)

Free this bio.

We allow talloc_free() to be called on just about anything in the bio chain. But we ensure that the chain is always shut down in an orderly fashion.

Definition at line 35 of file base.c.

Here is the caller graph for this function:

fr_bio_head()

static fr_bio_t * fr_bio_head ( fr_bio_t *  bio )

inlinestatic

Definition at line 140 of file base.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_next()

static fr_bio_t * fr_bio_next ( fr_bio_t *  bio )

inlinestatic

Definition at line 131 of file base.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_prev()

static fr_bio_t * fr_bio_prev ( fr_bio_t *  bio )

inlinestatic

Definition at line 122 of file base.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_read()

static ssize_t fr_bio_read ( fr_bio_t *  bio, void *  packet_ctx, void *  buffer, size_t  size  )

inlinestatic

Read raw data from a bio.

Parameters

bio	the binary IO handler
packet_ctx	packet-specific data associated with the buffer
buffer	where to read the data
size	amount of data to read.

Returns

• <0 for error. The return code will be fr_bio_error(ERROR_NAME)
• 0 for "did not read any data". EOF is a separate signal.

Definition at line 161 of file base.h.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_shutdown()

int fr_bio_shutdown

(

fr_bio_t *

bio

)

Shut down a set of BIOs.

We shut down the BIOs from the top to the bottom. This gives the TLS BIO an opportunity to call the SSL_shutdown() routine, which should then write to the FD BIO. Once that write is completed, the FD BIO can then close its socket.

Any shutdown is "stop read / write", but is not "free all resources". A shutdown can happen when one of the intermediary BIOs hits a fatal error. It can't free the BIO, but it has to mark the entire BIO chain as being unusable.

A destructor will first shutdown the BIOs, and then free all resources.

Definition at line 98 of file base.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_shutdown_intermediate()

int fr_bio_shutdown_intermediate

(

fr_bio_t *

bio

)

Like fr_bio_shutdown(), but can be called by anyone in the chain.

Definition at line 150 of file base.c.

Here is the call graph for this function:

fr_bio_shutdown_read()

ssize_t fr_bio_shutdown_read	(	fr_bio_t *	bio,
		void *	packet_ctx,
		void *	buffer,
		size_t	size
	)

fr_bio_shutdown_write()

ssize_t fr_bio_shutdown_write	(	fr_bio_t *	bio,
		void *	packet_ctx,
		void const *	buffer,
		size_t	size
	)

fr_bio_strerror()

char const * fr_bio_strerror

(

ssize_t

error

)

Definition at line 161 of file base.c.

Here is the call graph for this function:

Here is the caller graph for this function:

fr_bio_write()

static ssize_t fr_bio_write ( fr_bio_t *  bio, void *  packet_ctx, void const *  buffer, size_t  size  )

inlinestatic

Write raw data to a bio.

Parameters

bio	the binary IO handler
packet_ctx	packet-specific data associated with the buffer
buffer	the data to write. If NULL, will "flush" any pending data.
size	amount of data to write. For flush, it should be SIZE_MAX

Returns

• <0 for error. The return code will be fr_bio_error(ERROR_NAME)
• 0 for "did not write any data"
• >0 for amount of data written. Should always be equal to size!

Definition at line 184 of file base.h.

Here is the call graph for this function:

Here is the caller graph for this function: