xcm_attr.h File Reference

XCM socket attribute access API. More...

#include <stdbool.h>
#include <stdarg.h>
#include <xcm.h>
#include <xcm_attr_types.h>

Go to the source code of this file.

Typedefs
typedef void(*	xcm_attr_cb) (const char *attr_name, enum xcm_attr_type type, void *value, size_t value_len, void *cb_data)

Functions
int	xcm_attr_set (struct xcm_socket *socket, const char *name, enum xcm_attr_type type, const void *value, size_t len)
int	xcm_attr_set_bool (struct xcm_socket *socket, const char *name, bool value)
int	xcm_attr_set_int64 (struct xcm_socket *socket, const char *name, int64_t value)
int	xcm_attr_set_double (struct xcm_socket *socket, const char *name, double value)
int	xcm_attr_set_str (struct xcm_socket *socket, const char *name, const char *value)
int	xcm_attr_get (struct xcm_socket *socket, const char *name, enum xcm_attr_type *type, void *value, size_t capacity)
int	xcm_attr_get_bool (struct xcm_socket *socket, const char *name, bool *value)
int	xcm_attr_get_int64 (struct xcm_socket *socket, const char *name, int64_t *value)
int	xcm_attr_get_double (struct xcm_socket *socket, const char *name, double *value)
int	xcm_attr_get_str (struct xcm_socket *socket, const char *name, char *value, size_t capacity)
int	xcm_attr_get_bin (struct xcm_socket *socket, const char *name, void *value, size_t capacity)
int	xcm_attr_getf (struct xcm_socket *socket, enum xcm_attr_type *type, void *value, size_t capacity, const char *fmt,...)
int	xcm_attr_getf_bool (struct xcm_socket *socket, bool *value, const char *name_fmt,...)
int	xcm_attr_getf_int64 (struct xcm_socket *socket, int64_t *value, const char *name_fmt,...)
int	xcm_attr_getf_double (struct xcm_socket *socket, double *value, const char *name_fmt,...)
int	xcm_attr_getf_str (struct xcm_socket *socket, char *value, size_t capacity, const char *name_fmt,...)
int	xcm_attr_getf_bin (struct xcm_socket *socket, void *value, size_t capacity, const char *name_fmt,...)
int	xcm_attr_get_list_len (struct xcm_socket *socket, const char *list_name)
void	xcm_attr_get_all (struct xcm_socket *socket, xcm_attr_cb cb, void *cb_data)

Detailed Description

XCM socket attribute access API.

See Socket Attributes for an overview.

Typedef Documentation

xcm_attr_cb

typedef void(* xcm_attr_cb) (const char *attr_name, enum xcm_attr_type type, void *value, size_t value_len, void *cb_data)

The signature of the user-supplied callback used in xcm_attr_get_all().

Function Documentation

xcm_attr_set()

int xcm_attr_set	(	struct xcm_socket *	socket,
		const char *	name,
		enum xcm_attr_type	type,
		const void *	value,
		size_t	len
	)

Sets the value of a socket attribute.

Only attributes marked as writable may be set. For a list of available attributes for different socket and transport types, see Generic Attributes, TCP Socket Attributes and TLS Socket Attributes.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	type	The value type of the new value.
[in]	value	The new value.
[in]	len	The length of the value.

Returns

Returns the 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist.
EACCES	The attribute exists, but is read-only.
EINVAL	The attribute name has an invalid syntax or is too long, or the attribute value type, value or value length is not valid for the specified attribute.

xcm_attr_set_bool()

int xcm_attr_set_bool	(	struct xcm_socket *	socket,
		const char *	name,
		bool	value
	)

Sets the value of a boolean socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new boolean value.

Returns

Returns the 0 on success, or -1 if an error occured (in which case errno is set).

See xcm_attr_set() for possible errno values.

xcm_attr_set_int64()

int xcm_attr_set_int64	(	struct xcm_socket *	socket,
		const char *	name,
		int64_t	value
	)

Sets the value of an integer socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new integer value.

Returns

Returns the 0 on success, or -1 if an error occured (in which case errno is set).

See xcm_attr_set() for possible errno values.

xcm_attr_set_double()

int xcm_attr_set_double	(	struct xcm_socket *	socket,
		const char *	name,
		double	value
	)

Sets the value of a double type socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new double-precision floating point value.

Returns

Returns the 0 on success, or -1 if an error occured (in which case errno is set).

See xcm_attr_set() for possible errno values.

xcm_attr_set_str()

int xcm_attr_set_str	(	struct xcm_socket *	socket,
		const char *	name,
		const char *	value
	)

Sets the value of a string socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new string value.

Returns

Returns the 0 on success, or -1 if an error occured (in which case errno is set).

See xcm_attr_set() for possible errno values.

xcm_attr_get()

int xcm_attr_get	(	struct xcm_socket *	socket,
		const char *	name,
		enum xcm_attr_type *	type,
		void *	value,
		size_t	capacity
	)

Retrieves the value of a socket attribute.

For a list of available attributes for different socket and transport types, see Generic Attributes, TCP Socket Attributes and TLS Socket Attributes.

For a description of the C types and buffer capacity requirements of the attribute types, see xcm_attr_types.h.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	type	A pointer to a location where the type of the attribute will be stored. May be left to NULL, in case the type is known a priori.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).

Returns

Returns the length of the value on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist.
EACCES	The attribute exists, but is write-only.
EOVERFLOW	The user-supplied buffer was too small to fit the value.
EINVAL	The attribute name has an invalid syntax or is too long.

xcm_attr_get_bool()

int xcm_attr_get_bool	(	struct xcm_socket *	socket,
		const char *	name,
		bool *	value
	)

Retrieves the value of a boolean socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.

Returns

Returns sizeof(bool) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not boolean.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_int64()

int xcm_attr_get_int64	(	struct xcm_socket *	socket,
		const char *	name,
		int64_t *	value
	)

Retrieves the value of an integer socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.

Returns

Returns sizeof(int64_t) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not an integer.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_double()

int xcm_attr_get_double	(	struct xcm_socket *	socket,
		const char *	name,
		double *	value
	)

Retrieves the value of a double type socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.

Returns

Returns sizeof(double) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not of type double.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_str()

int xcm_attr_get_str	(	struct xcm_socket *	socket,
		const char *	name,
		char *	value,
		size_t	capacity
	)

Retrieves the value of a string socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the string value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).

Returns

Returns the length of the string value (including the terminating NUL character) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not a string.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_bin()

int xcm_attr_get_bin	(	struct xcm_socket *	socket,
		const char *	name,
		void *	value,
		size_t	capacity
	)

Retrieves the value of a binary socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).

Returns

Returns the length of the binary value on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not of the binary type.

See xcm_attr_get() for other possible errno values.

xcm_attr_getf()

int xcm_attr_getf	(	struct xcm_socket *	socket,
		enum xcm_attr_type *	type,
		void *	value,
		size_t	capacity,
		const char *	fmt,
			...
	)

Retrieves the value of a socket attribute using a formatted name.

This function builds an attribute name using the user-provided format string and arguments, and calls xcm_attr_get().

xcm_attr_getf() may be used to access a particular element in a list, for example.

The format string has the same syntax as that of printf().

Parameters

[in]	socket	The connection or server socket.
[out]	type	A pointer to a location where the type of the attribute will be stored. May be left to NULL, in case the type is known a priori.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).
[in]	name_fmt	The format string.

Returns

Returns the length of the value on success, or -1 if an error occured (in which case errno is set).

See xcm_attr_get() for possible errno values.

xcm_attr_getf_bool()

int xcm_attr_getf_bool	(	struct xcm_socket *	socket,
		bool *	value,
		const char *	name_fmt,
			...
	)

Retrieves the value of a boolean socket attribute using a formatted name.

Parameters

[in]	socket	The connection or server socket.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	name_fmt	The format string.

Returns

Returns sizeof(bool) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not boolean.

See xcm_attr_get() for other possible errno values.

xcm_attr_getf_int64()

int xcm_attr_getf_int64	(	struct xcm_socket *	socket,
		int64_t *	value,
		const char *	name_fmt,
			...
	)

Retrieves the value of an integer socket attribute using a formatted name.

Parameters

[in]	socket	The connection or server socket.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	name_fmt	The format string.

Returns

Returns sizeof(int64_t) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not an integer.

See xcm_attr_get() for other possible errno values.

xcm_attr_getf_double()

int xcm_attr_getf_double	(	struct xcm_socket *	socket,
		double *	value,
		const char *	name_fmt,
			...
	)

Retrieves the value of a double type socket attribute using a formatted name.

Parameters

[in]	socket	The connection or server socket.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	name_fmt	The format string.

Returns

Returns sizeof(double) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not of type double.

See xcm_attr_get() for other possible errno values.

xcm_attr_getf_str()

int xcm_attr_getf_str	(	struct xcm_socket *	socket,
		char *	value,
		size_t	capacity,
		const char *	name_fmt,
			...
	)

Retrieves the value of a string socket attribute using a formatted name.

Parameters

[in]	socket	The connection or server socket.
[out]	value	A user-supplied buffer where the string value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).
[in]	name_fmt	The format string.

Returns

Returns the length of the string value (including the terminating NUL character) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not a string.

See xcm_attr_get() for other possible errno values.

xcm_attr_getf_bin()

int xcm_attr_getf_bin	(	struct xcm_socket *	socket,
		void *	value,
		size_t	capacity,
		const char *	name_fmt,
			...
	)

Retrieves the value of a binary socket attribute using a formatted name.

Parameters

[in]	socket	The connection or server socket.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).
[in]	name_fmt	The format string.

Returns

Returns the length of the binary value on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not of the binary type.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_list_len()

int xcm_attr_get_list_len	(	struct xcm_socket *	socket,
		const char *	list_name
	)

Get the length of a socket attribute list.

Query the number of elements in a list in the socket attribute tree.

Parameters

[in]	socket	The connection or server socket.
[in]	list_name	The name of the attribute list.

Returns

Returns the length of the list on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not a list.
EACCES	The attribute exists, but is write-only.
EINVAL	The attribute name has an invalid syntax or is too long.

xcm_attr_get_all()

void xcm_attr_get_all	(	struct xcm_socket *	socket,
		xcm_attr_cb	cb,
		void *	cb_data
	)

Retrieves all XCM socket attributes.

This function retrieves the name, type and current value of all available socket attributes on a particular connection or server socket.

The memory locations refered to by the attr_name and attr_value pointers is only guaranteed to be valid for the execution of the callback. If needed later, they need to be copied.

Parameters

[in]	socket	The connection or server socket.
[in]	cb	The function to be called for every attribute on the socket.
[in]	cb_data	An opaque (for XCM) pointer returned back to the application in the callback. cb_data may be NULL.