sideband.c File Reference

Implementation of the sideband API. More...

#include <regex.h>
#include "para.h"
#include "error.h"
#include "portable_io.h"
#include "string.h"
#include "sideband.h"

Macros
#define	SIDEBAND_HEADER_SIZE   5
	Each sideband packet consists of a header and a data part. More...

Functions
struct sb_context *	sb_new_recv (size_t max_size, sb_transformation t, void *trafo_context)
	Prepare to receive a sideband packet. More...
struct sb_context *	sb_new_send (struct sb_buffer *sbb, bool dont_free, sb_transformation t, void *trafo_context)
	Prepare to write a sideband packet. More...
void	sb_free (struct sb_context *c)
	Deallocate all memory associated with a sideband handle. More...
int	sb_get_send_buffers (struct sb_context *c, struct iovec iov[2])
	Obtain pointer(s) to the sideband send buffer(s). More...
bool	sb_sent (struct sb_context *c, size_t nbytes)
	Update the sideband context after data has been sent. More...
void	sb_get_recv_buffer (struct sb_context *c, struct iovec *iov)
	Obtain a pointer to the next sideband read buffer. More...
int	sb_received (struct sb_context *c, size_t nbytes, struct sb_buffer *result)
	Update the sideband context after data has been received. More...

Detailed Description

Implementation of the sideband API.

Macro Definition Documentation

SIDEBAND_HEADER_SIZE

#define SIDEBAND_HEADER_SIZE   5

Each sideband packet consists of a header and a data part.

Function Documentation

sb_new_recv()

struct sb_context* sb_new_recv	(	size_t	max_size,
		sb_transformation	t,
		void *	trafo_context
	)

Prepare to receive a sideband packet.

Parameters

max_size	Do not allocate more than this many bytes.
t	Optional sideband transformation.
trafo_context	Passed verbatim to t.

trafo_context is ignored if t is NULL.

Returns

An opaque sideband handle.

References zalloc().

Referenced by recv_sb().

sb_new_send()

struct sb_context* sb_new_send	(	struct sb_buffer *	sbb,
		bool	dont_free,
		sb_transformation	t,
		void *	trafo_context
	)

Prepare to write a sideband packet.

Parameters

sbb	Data and meta data to send.
dont_free	Do not try to deallocate the sideband buffer.
t	See sb_new_recv().
trafo_context	See sb_new_recv().

It's OK to supply a zero-sized buffer in sbb. In this case only the band designator is sent through the sideband channel. Otherwise, if dont_free is false, the buffer of sbb is freed after the data has been sent.

Returns

See sb_new_recv().

References zalloc().

Referenced by send_sb().

sb_free()

void sb_free

(

struct sb_context *

c

)

Deallocate all memory associated with a sideband handle.

Parameters

c	The sideband handle.

c must point to a handle previously returned by sb_new_recv() or sb_new_send(). It c is NULL, the function does nothing.

Referenced by recv_sb(), sb_sent(), and send_sb().

sb_get_send_buffers()

int sb_get_send_buffers	(	struct sb_context *	c,
		struct iovec	iov[2]
	)

Obtain pointer(s) to the sideband send buffer(s).

Parameters

c	The sideband handle.
iov	Array of two I/O vectors.

Returns

The number of buffers that need to be sent, either 1 or 2.

This function fills out the buffers described by iov. The result can be passed to xwritev() or similar.

See also

sb_get_recv_buffer().

References sb_buffer::iov, iov_valid(), and SIDEBAND_HEADER_SIZE.

Referenced by send_sb().

sb_sent()

bool sb_sent	(	struct sb_context *	c,
		size_t	nbytes
	)

Update the sideband context after data has been sent.

Parameters

c	The sideband handle.
nbytes	The number of sent bytes.

Returns

False if more data must be sent to complete the sideband transfer, true if the transfer is complete. In this case all resources are freed and the sideband handle must not be used any more.

References sb_buffer::iov, sb_free(), and SIDEBAND_HEADER_SIZE.

Referenced by send_sb().

sb_get_recv_buffer()

void sb_get_recv_buffer	(	struct sb_context *	c,
		struct iovec *	iov
	)

Obtain a pointer to the next sideband read buffer.

Parameters

c	The sideband handle.
iov	Result IO vector.

This fills in iov to point to the buffer to which the next chunk of received data should be written.

References sb_buffer::iov, and SIDEBAND_HEADER_SIZE.

Referenced by recv_sb().

sb_received()

int sb_received	(	struct sb_context *	c,
		size_t	nbytes,
		struct sb_buffer *	result
	)

Update the sideband context after data has been received.

Parameters

c	The sideband handle.
nbytes	The number of bytes that have been received.
result	The received sideband packet.

Returns

Negative on errors, zero if more data needs to be read to complete this sideband packet, one if the sideband packet has been received completely.

Only if the function returns one, the sideband buffer pointed to by result is set to point to the received data.

References sb_buffer::iov, and SIDEBAND_HEADER_SIZE.

Referenced by recv_sb().