Binary IO abstractions for file descriptors. More...

#include <freeradius-devel/bio/base.h>
#include <freeradius-devel/util/socket.h>
#include <freeradius-devel/util/event.h>
#include <freeradius-devel/server/cf_parse.h>
#include <fcntl.h>

Include dependency graph for fd.h:

Go to the source code of this file.

Data Structures
struct	fr_bio_fd_config_t
	Configuration for sockets. More...

struct	fr_bio_fd_info_t
	Run-time status of the socket. More...

struct	fr_bio_fd_packet_ctx_t
	Per-packet context. More...

Macros
#define	fr_bio_fd_connect(_x) fr_bio_fd_connect_full(_x, NULL, NULL, NULL, NULL, NULL)

#define	FR_BIO_FD_TRANSPORT_SIZE (FR_BIO_FD_TRANSPORT_UNIX + 1)

Enumerations
enum	fr_bio_fd_state_t : uint8_t { FR_BIO_FD_STATE_INVALID = 0 , FR_BIO_FD_STATE_CLOSED , FR_BIO_FD_STATE_OPEN , FR_BIO_FD_STATE_CONNECTING }

enum	fr_bio_fd_transport_t : uint8_t { FR_BIO_FD_TRANSPORT_INVALID = 0 , FR_BIO_FD_TRANSPORT_FILE , FR_BIO_FD_TRANSPORT_TCP , FR_BIO_FD_TRANSPORT_UDP , FR_BIO_FD_TRANSPORT_UNIX }
	The type of transport used by a FD BIO. More...

enum	fr_bio_fd_type_t : uint8_t { FR_BIO_FD_INVALID , FR_BIO_FD_UNCONNECTED , FR_BIO_FD_CONNECTED , FR_BIO_FD_LISTEN }

Functions
int	fr_bio_fd_accept (TALLOC_CTX ctx, fr_bio_t out, fr_bio_t bio)
	Accept a new connection on a socket.

fr_bio_t *	fr_bio_fd_alloc (TALLOC_CTX ctx, fr_bio_fd_config_t const cfg, size_t offset))
	Allocate a FD bio.

int	fr_bio_fd_check_config (fr_bio_fd_config_t const *cfg)
	Checks the configuration without modifying anything.

int	fr_bio_fd_close (fr_bio_t *bio)
	Close the FD, but leave the bio allocated and alive.

int	fr_bio_fd_connect_full (fr_bio_t bio, fr_event_list_t el, fr_bio_callback_t connected_cb, fr_bio_callback_t error_cb, fr_time_delta_t *timeout, fr_bio_callback_t timeout_cb))
	Finalize a connect()

fr_bio_fd_info_t const *	fr_bio_fd_info (fr_bio_t *bio)
	Returns a pointer to the bio-specific information.

int	fr_bio_fd_open (fr_bio_t bio, fr_bio_fd_config_t const cfg)
	Opens a socket and updates sock->fd.

int	fr_bio_fd_reopen (fr_bio_t *bio)
	Reopen a file BIO.

int	fr_bio_fd_write_only (fr_bio_t *bio)
	Mark up a bio as write-only.

Variables
const conf_parser_t	fr_bio_fd_client_config []

const conf_parser_t	fr_bio_fd_server_config []

Detailed Description

Binary IO abstractions for file descriptors.

Id: 1c2f3291b65ba43df120d120d934f0875234e9c4

Allow reads and writes from file descriptors.

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

Definition in file fd.h.

Data Structure Documentation

◆ fr_bio_fd_config_t

struct fr_bio_fd_config_t

Configuration for sockets.

Each piece of information is broken out into a separate field, so that the configuration file parser can parse each field independently.

We also include more information here than we need in an fr_socket_t.

Definition at line 92 of file fd.h.

Collaboration diagram for fr_bio_fd_config_t:

Data Fields
bool	async	is it async
uint32_t	backlog	for listen()
bool	backlog_is_set	Whether we were provided with a backlog.
fr_ipaddr_t	dst_ipaddr	their IP address
uint16_t	dst_port	their port
bool	exceed_mtu	Whether we allow packets which exceed the local MTU.
char const *	filename	for files
int	flags	O_RDONLY, etc.
gid_t	gid	who owns the socket
char const *	interface	for binding to an interface
bool	mkdir	make intermediate directories
char const *	path	for Unix domain sockets
mode_t	perm	permissions for domain sockets
uint32_t	recv_buff	How big the kernel's receive buffer should be.
bool	recv_buff_is_set	Whether we were provided with a recv_buf.
bool	reuse_port	whether or not we re-use the same destination port for datagram sockets
uint32_t	send_buff	How big the kernel's send buffer should be.
bool	send_buff_is_set	Whether we were provided with a send_buf.
bool	server	is this a client or a server?
int	socket_type	SOCK_STREAM or SOCK_DGRAM.
fr_ipaddr_t	src_ipaddr	our IP address
uint16_t	src_port	our port
uint16_t	src_port_end	limit source port ranges for client BIOs
uint16_t	src_port_start	limit source port ranges for client BIOs
bool	tcp_delay	We do tcp_nodelay by default.
char const *	transport	name of the transport protocol
fr_bio_fd_transport_t	transport_type	which transport, as a number instead of a name
fr_bio_fd_type_t	type	accept, connected, unconnected, etc.
uid_t	uid	who owns the socket

◆ fr_bio_fd_info_t

struct fr_bio_fd_info_t

Run-time status of the socket.

Definition at line 144 of file fd.h.

Collaboration diagram for fr_bio_fd_info_t:

Data Fields
fr_bio_fd_config_t const *	cfg	so we know what was asked, vs what was granted.
int	connect_errno	from connect() or other APIs
bool	eof	are we at EOF?
char const *	name	printable name of this BIO
bool	read_blocked	did we block on read?
fr_socket_t	socket	as connected socket
fr_bio_fd_state_t	state	connecting, open, closed, etc.
fr_bio_fd_type_t	type	type of the socket
bool	write_blocked	did we block on write?

◆ fr_bio_fd_packet_ctx_t

struct fr_bio_fd_packet_ctx_t

Per-packet context.

For reading packets src_ip is *their* IP, and dst_ip is *our* IP.

For writing packets, src_ip is *our* IP, and dst_ip is *their* IP.

This context is returned only for datagram sockets.  For stream sockets (TCP and Unix domain), it
isn't used.  The caller can look at the socket information to determine src/dst ip/port.

Definition at line 46 of file fd.h.

Collaboration diagram for fr_bio_fd_packet_ctx_t:

Data Fields
fr_socket_t	socket	socket information, including FD.
fr_time_t	when	when the packet was received

Macro Definition Documentation

◆ fr_bio_fd_connect

#define fr_bio_fd_connect ( _x ) fr_bio_fd_connect_full(_x, NULL, NULL, NULL, NULL, NULL)

Definition at line 169 of file fd.h.

◆ FR_BIO_FD_TRANSPORT_SIZE

#define FR_BIO_FD_TRANSPORT_SIZE (FR_BIO_FD_TRANSPORT_UNIX + 1)

Definition at line 83 of file fd.h.

Enumeration Type Documentation

◆ fr_bio_fd_state_t

enum fr_bio_fd_state_t : uint8_t

Enumerator
FR_BIO_FD_STATE_INVALID
FR_BIO_FD_STATE_CLOSED
FR_BIO_FD_STATE_OPEN	error states must be before this
FR_BIO_FD_STATE_CONNECTING

Definition at line 51 of file fd.h.

◆ fr_bio_fd_transport_t

enum fr_bio_fd_transport_t : uint8_t

The type of transport used by a FD BIO.

The transport defines where the data goes (files, socket, etc), not the format of the transport (datagram or stream). It also is largely independent of connected vs unconnected. A TCP socket can be connected or listening, and a UDP socket can be connected or unconnected.

This field is set automatically when parsing the configuration.

Enumerator
FR_BIO_FD_TRANSPORT_INVALID	not set
FR_BIO_FD_TRANSPORT_FILE	regular file, named by 'filename'
FR_BIO_FD_TRANSPORT_TCP	TCP over IPv4 or IPv6.
FR_BIO_FD_TRANSPORT_UDP	UDP over IPv4 or IPv6.
FR_BIO_FD_TRANSPORT_UNIX	Unix domain socket, named by 'path'.

Definition at line 76 of file fd.h.

◆ fr_bio_fd_type_t

enum fr_bio_fd_type_t : uint8_t

Enumerator
FR_BIO_FD_INVALID	not set
FR_BIO_FD_UNCONNECTED	unconnected UDP / datagram only
FR_BIO_FD_CONNECTED	connected client sockets (UDP or TCP)
FR_BIO_FD_LISTEN	call fr_bio_fd_accept() for each new connection

Definition at line 58 of file fd.h.

Function Documentation

◆ fr_bio_fd_accept()

int fr_bio_fd_accept	(	TALLOC_CTX *	ctx,
		fr_bio_t **	out,
		fr_bio_t *	bio
	)

Accept a new connection on a socket.

Definition at line 1561 of file fd.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_alloc()

fr_bio_t * fr_bio_fd_alloc	(	TALLOC_CTX *	ctx,
		fr_bio_fd_config_t const *	cfg,
		size_t	offset
	)

Allocate a FD bio.

The caller is responsible for tracking the FD, and all associated management of it. The bio API is intended to be simple, and does not provide wrapper functions for various ioctls. The caller should instead do that work.

Once the FD is give to the bio, its lifetime is "owned" by the bio. Calling talloc_free(bio) will close the FD.

The caller can still manage the FD for being readable / writeable. However, the caller should not call this bio directly (unless it is the only one). Instead, the caller should read from / write to the previous bio which will then eventually call this one.

Before updating any event handler readable / writeable callbacks, the caller should check fr_bio_fd_at_eof(). If true, then the handlers should not be inserted. The previous bios should still be called to process any pending data, until they return EOF.

The main purpose of an FD bio is to wrap the FD in a bio container. That, and handling retries on read / write, along with returning EOF as an error instead of zero.

Note that the read / write functions can return partial data. It is the callers responsibility to ensure that any writes continue from where they left off (otherwise dat awill be missing). And any partial reads should go to a memory bio.

If a read returns EOF, then the FD remains open until talloc_free(bio) or fr_bio_fd_close() is called.

The bio caches the cfg pointer, so the configuration has to live at least as long as the bio does. See fr_bio_fd_open().

Parameters

ctx	the talloc ctx
cfg	structure holding the configuration information
offset	only for unconnected datagram sockets, where fr_bio_fd_packet_ctx_t is stored

Returns

NULL on error, memory allocation failed
!NULL the bio

Definition at line 1047 of file fd.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_check_config()

int fr_bio_fd_check_config ( fr_bio_fd_config_t const * cfg )

Checks the configuration without modifying anything.

Definition at line 996 of file fd_open.c.

Here is the caller graph for this function:

◆ fr_bio_fd_close()

int fr_bio_fd_close ( fr_bio_t * bio )

Close the FD, but leave the bio allocated and alive.

Definition at line 1095 of file fd.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_connect_full()

int fr_bio_fd_connect_full	(	fr_bio_t *	bio,
		fr_event_list_t *	el,
		fr_bio_callback_t	connected_cb,
		fr_bio_callback_t	error_cb,
		fr_time_delta_t *	timeout,
		fr_bio_callback_t	timeout_cb
	)

Finalize a connect()

connect() said "come back when the socket is writeable". It's now writeable, so we check if there was a connection error.

Parameters

bio	the binary IO handler
el	the event list
connected_cb	callback to run when the BIO is connected
error_cb	callback to run when the FD has an error
timeout	when to time out the connect() attempt
timeout_cb	to call when the timeout runs.

Returns

<0 on error
0 for "try again later". If callbacks are set, the callbacks will try again. Otherwise the application has to try again.
1 for "we are now connected".

Definition at line 1280 of file fd.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_info()

fr_bio_fd_info_t const * fr_bio_fd_info ( fr_bio_t * bio )

Returns a pointer to the bio-specific information.

Definition at line 1377 of file fd.c.

Here is the caller graph for this function:

◆ fr_bio_fd_open()

int fr_bio_fd_open	(	fr_bio_t *	bio,
		fr_bio_fd_config_t const *	cfg
	)

Opens a socket and updates sock->fd.

If the socket is asynchronous, it also calls connect()

The caller must supply a cfg pointer which is long-lived. The FD BIO doesn't copy it, or its contents. fr_bio_fd_accept() uses the same pointer for accepted sockets.

Parameters

bio	the FD bio
cfg	configuration for the socket, which the caller owns and must keep alive

Returns

<0 on error
0 on success

Definition at line 1293 of file fd_open.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_reopen()

int fr_bio_fd_reopen ( fr_bio_t * bio )

Reopen a file BIO.

e.g. for log files.

This will change the FD which is in the BIO.

Definition at line 1500 of file fd_open.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_bio_fd_write_only()

int fr_bio_fd_write_only ( fr_bio_t * bio )

Mark up a bio as write-only.

Definition at line 1424 of file fd.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ fr_bio_fd_client_config

const conf_parser_t fr_bio_fd_client_config[]

extern

Definition at line 314 of file fd_config.c.

◆ fr_bio_fd_server_config

const conf_parser_t fr_bio_fd_server_config[]

extern

Definition at line 485 of file fd_config.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ fr_bio_fd_config_t

◆ fr_bio_fd_info_t

◆ fr_bio_fd_packet_ctx_t

Macro Definition Documentation

◆ fr_bio_fd_connect

◆ FR_BIO_FD_TRANSPORT_SIZE

Enumeration Type Documentation

◆ fr_bio_fd_state_t

◆ fr_bio_fd_transport_t

◆ fr_bio_fd_type_t

Function Documentation

◆ fr_bio_fd_accept()

◆ fr_bio_fd_alloc()

◆ fr_bio_fd_check_config()

◆ fr_bio_fd_close()

◆ fr_bio_fd_connect_full()

◆ fr_bio_fd_info()

◆ fr_bio_fd_open()

◆ fr_bio_fd_reopen()

◆ fr_bio_fd_write_only()

Variable Documentation

◆ fr_bio_fd_client_config

◆ fr_bio_fd_server_config