Data Structures
struct	scion_path_interface
	An interface of an AS in a SCION path. More...

struct	scion_geo_coordinates
	The geographic location of an AS. More...

struct	scion_path_metadata
	The metadata of a SCION path. More...

struct	scion_path_predicate
	A path predicate. More...

struct	scion_path_comparator
	A path comparator. More...

struct	scion_policy

struct	scion_scmp_echo

Macros
#define	SCION_SO_DEBUG 200

#define	SCION_FETCH_OPT_DEBUG 1

#define	SCION_IA_STRLEN 21

#define	SCION_PATH_METADATA_LATENCY_IS_UNSET(latency) (latency.tv_sec == 0 && latency.tv_usec == -1)

#define	SCION_PATH_METADATA_BANDWIDTH_IS_UNSET(bandwidth) (bandwidth == 0)

#define	SCION_PATH_METADATA_GEO_IS_UNSET(geo) (geo.latitude == NAN && geo.longitude == NAN && geo.address == NULL)

#define	SCION_PATH_METADATA_INTERNAL_HOPS_IS_UNSET(internal_hops) (internal_hops == 0)

Typedefs
typedef uint64_t	scion_ia

typedef uint64_t	scion_ifid

typedef bool(*	scion_path_predicate_fn) (struct scion_path path, void ctx)

typedef int(*	scion_path_comparator_fn) (struct scion_path path_one, struct scion_path path_two, void *ctx)

typedef void(*	scion_policy_fn) (struct scion_path_collection paths, void ctx)

typedef void	scion_socket_scmp_error_cb(uint8_t buf, size_t size, void ctx)

Enumerations
enum	scion_error { SCION_ERR_GENERIC = -1 , SCION_ERR_MEM_ALLOC_FAIL = -2 , SCION_ERR_NO_PATHS = -3 , SCION_ERR_BUF_TOO_SMALL = -4 , SCION_ERR_ADDR_FAMILY_UNKNOWN = -5 , SCION_ERR_MAX_HDR_LEN_EXCEEDED = -6 , SCION_ERR_FILE_NOT_FOUND = -7 , SCION_ERR_TOPOLOGY_INVALID = -8 , SCION_ERR_ADDR_FAMILY_MISMATCH = -9 , SCION_ERR_NETWORK_ADDR_FAMILY_MISMATCH = -10 , SCION_ERR_PROTO_UNKNOWN = -11 , SCION_ERR_NOT_CONNECTED = -12 , SCION_ERR_DST_MISMATCH = -13 , SCION_ERR_INVALID_ISD_AS_STR = -14 , SCION_ERR_WOULD_BLOCK = -15 , SCION_ERR_ADDR_INVALID = -16 , SCION_ERR_ALREADY_BOUND = -17 , SCION_ERR_FLAG_NOT_IMPLEMENTED = -18 , SCION_ERR_FLAG_NOT_SUPPORTED = -19 , SCION_ERR_SEND_FAIL = -20 , SCION_ERR_RECV_FAIL = -21 , SCION_ERR_ADDR_IN_USE = -22 , SCION_ERR_ADDR_NOT_AVAILABLE = -23 , SCION_ERR_OUTPUT_QUEUE_FULL = -24 , SCION_ERR_SOCK_OPT_INVALID = -25 , SCION_ERR_ADDR_BUF_TOO_SMALL = -26 , SCION_ERR_PATH_EXPIRED = -27 , SCION_ERR_NOT_BOUND = -28 , SCION_ERR_NETWORK_UNKNOWN = -29 , SCION_ERR_MSG_TOO_LARGE = -30 , SCION_ERR_SRC_ADDR_UNKNOWN = -31 , SCION_ERR_BOOTSTRAPPING_FAIL = -32 , SCION_ERR_NOT_ENOUGH_DATA = -201 , SCION_ERR_PACKET_FIELD_INVALID = -202 , SCION_ERR_GRPC_FAIL = -203 , SCION_ERR_META_HDR_INVALID = -204 , SCION_ERR_PATH_TYPE_INVALID = -205 , SCION_ERR_SCMP_CODE_INVALID = -206 }

enum	scion_addr_family { SCION_AF_INET = AF_INET , SCION_AF_INET6 = AF_INET6 }

enum	scion_proto { SCION_PROTO_UDP = 17 , SCION_PROTO_SCMP = 202 }

enum	scion_link_type { SCION_LINK_TYPE_UNSPECIFIED = 0 , SCION_LINK_TYPE_DIRECT = 1 , SCION_LINK_TYPE_MULTI_HOP = 2 , SCION_LINK_TYPE_OPEN_NET = 3 }

enum	scion_scmp_echo_type { SCION_ECHO_TYPE_REQUEST = 128 , SCION_ECHO_TYPE_REPLY = 129 }

Functions
char *	scion_strerror (int err)

int	scion_ia_parse (const char str, size_t len, scion_ia ia)

int	scion_ia_str (scion_ia ia, char *buf, size_t buflen)

void	scion_ia_print (scion_ia ia)

int	scion_topology_from_file (struct scion_topology *topology, const char path)

scion_ia	scion_topology_get_local_ia (struct scion_topology *topo)

void	scion_topology_free (struct scion_topology *topo)

int	scion_bootstrap (const char *topology_output_path)

int	scion_network (struct scion_network *net, struct scion_topology topology)

void	scion_network_free (struct scion_network *net)

enum scion_addr_family	scion_network_get_local_addr_family (struct scion_network *net)

int	scion_path_reverse (struct scion_path *path)

size_t	scion_path_get_numhops (const struct scion_path *path)

void	scion_path_free (struct scion_path *path)

const struct scion_path_metadata *	scion_path_get_metadata (const struct scion_path *path)

void	scion_path_print (const struct scion_path *path)

void	scion_path_print_metadata (const struct scion_path *path)

void	scion_path_collection_free (struct scion_path_collection *paths)

struct scion_path *	scion_path_collection_find (struct scion_path_collection *paths, struct scion_path_predicate predicate)

struct scion_path *	scion_path_collection_pop (struct scion_path_collection *paths)

struct scion_path *	scion_path_collection_first (struct scion_path_collection *paths)

void	scion_path_collection_sort (struct scion_path_collection *paths, struct scion_path_comparator comparator)

void	scion_path_collection_filter (struct scion_path_collection *paths, struct scion_path_predicate predicate)

size_t	scion_path_collection_size (struct scion_path_collection *paths)

struct scion_path **	scion_path_collection_as_array (struct scion_path_collection paths, size_t len)

void	scion_path_collection_print (struct scion_path_collection *paths)

int	scion_path_collection_fetch (struct scion_network network, scion_ia dst, uint opt, struct scion_path_collection *paths)

struct scion_policy	scion_policy_min_mtu (uint32_t *mtu)

int	scion_socket (struct scion_socket *scion_sock, enum scion_addr_family addr_family, enum scion_proto protocol, struct scion_network network)

int	scion_bind (struct scion_socket scion_sock, const struct sockaddr addr, socklen_t addrlen)

int	scion_connect (struct scion_socket scion_sock, const struct sockaddr addr, socklen_t addrlen, scion_ia ia)

ssize_t	scion_send (struct scion_socket scion_sock, const void buf, size_t size, int flags)

ssize_t	scion_sendto (struct scion_socket scion_sock, const void buf, size_t size, int flags, const struct sockaddr dst_addr, socklen_t addrlen, scion_ia dst_ia, struct scion_path path)

ssize_t	scion_recv (struct scion_socket scion_sock, void buf, size_t size, int flags)

ssize_t	scion_recvfrom (struct scion_socket scion_sock, void buf, size_t size, int flags, struct sockaddr src_addr, socklen_t addrlen, scion_ia src_ia, struct scion_path *path)

int	scion_close (struct scion_socket *scion_sock)

int	scion_getsockopt (struct scion_socket scion_sock, int level, int optname, void optval, socklen_t *optlen)

int	scion_setsockopt (struct scion_socket scion_sock, int level, int optname, const void optval, socklen_t optlen)

int	scion_getsockname (struct scion_socket scion_sock, struct sockaddr addr, socklen_t addrlen, scion_ia ia)

int	scion_getsockfd (struct scion_socket scion_sock, int fd)

int	scion_setsockerrcb (struct scion_socket scion_sock, scion_socket_scmp_error_cb cb, void ctx)

int	scion_setsockpolicy (struct scion_socket *scion_sock, struct scion_policy policy)

void	scion_addr_print (const struct sockaddr *addr, scion_ia ia)

uint8_t	scion_scmp_get_type (const uint8_t *buf, uint16_t buf_len)

uint8_t	scion_scmp_get_code (const uint8_t *buf, uint16_t buf_len)

bool	scion_scmp_is_error (const uint8_t *buf, uint16_t buf_len)

uint16_t	scion_scmp_echo_len (struct scion_scmp_echo *scmp_echo)

int	scion_scmp_echo_serialize (const struct scion_scmp_echo scmp_echo, uint8_t buf, uint16_t buf_len)

int	scion_scmp_echo_deserialize (const uint8_t buf, uint16_t buf_len, struct scion_scmp_echo scmp_echo)

void	scion_scmp_echo_free_members (struct scion_scmp_echo *scmp_echo)

Variables
const struct scion_policy	scion_policy_highest_mtu

const struct scion_policy	scion_policy_least_hops

const struct scion_policy	scion_policy_lowest_latency

const struct scion_policy	scion_policy_highest_bandwidth

Detailed Description

The CSNET library.

Macro Definition Documentation

◆ SCION_IA_STRLEN

#define SCION_IA_STRLEN 21

The maximum length a string representation of an IA may require (including the null terminator).

◆ SCION_PATH_METADATA_LATENCY_IS_UNSET

#define SCION_PATH_METADATA_LATENCY_IS_UNSET ( latency ) (latency.tv_sec == 0 && latency.tv_usec == -1)

Returns true if the latency is unknown.

Parameters

latency The latency.

◆ SCION_PATH_METADATA_BANDWIDTH_IS_UNSET

#define SCION_PATH_METADATA_BANDWIDTH_IS_UNSET ( bandwidth ) (bandwidth == 0)

Returns true if the bandwidth is unknown.

Parameters

bandwidth The bandwidth.

◆ SCION_PATH_METADATA_GEO_IS_UNSET

#define SCION_PATH_METADATA_GEO_IS_UNSET ( geo ) (geo.latitude == NAN && geo.longitude == NAN && geo.address == NULL)

Returns true if the geographical location is unknown.

Parameters

geo	The geographical location.

◆ SCION_PATH_METADATA_INTERNAL_HOPS_IS_UNSET

#define SCION_PATH_METADATA_INTERNAL_HOPS_IS_UNSET ( internal_hops ) (internal_hops == 0)

Returns true if the number of internal hops is unknown.

Parameters

internal_hops The number of internal hops.

Typedef Documentation

◆ scion_ia

typedef uint64_t scion_ia

A fully qualified AS identifier called IA.

◆ scion_ifid

typedef uint64_t scion_ifid

An interface identifier.

◆ scion_path_predicate_fn

typedef bool(* scion_path_predicate_fn) (struct scion_path *path, void *ctx)

A function that matches a path with a custom context.

Parameters

path	The candidate path.
ctx	The custom context.

Returns: true, if the path matches the predicate; false, if the path does not match the predicate

◆ scion_path_comparator_fn

typedef int(* scion_path_comparator_fn) (struct scion_path *path_one, struct scion_path *path_two, void *ctx)

A function that compares two paths with a custom context.

Parameters

path_one	The first path.
path_two	The second path.
ctx	The custom context.

Returns: 1, if path_one > path_two; 0, if path_one == path_two; -1, if path_one < path_two

◆ scion_policy_fn

typedef void(* scion_policy_fn) (struct scion_path_collection *paths, void *ctx)

A function that implements the path selection policy by filtering and/or sorting the available paths contained in the path collection. The function must modify the path collection in-place. When sorting the paths, the most preferred path should be the first path.

Parameters

[in,out]	paths	The path collection.
[in]	ctx	The user-defined context that was provided when creating the policy.

See also: scion_path_collection_filter, scion_path_collection_sort

◆ scion_socket_scmp_error_cb

typedef void scion_socket_scmp_error_cb(uint8_t *buf, size_t size, void *ctx)

A callback for SCMP error handling.

Parameters

buf	The buffer containing the SCMP error message.
size	The size of the buffer.
ctx	The context that was provided when setting up the callback.

See also: scion_setsockerrcb

Enumeration Type Documentation

◆ scion_error

enum scion_error

Possible error codes returned by the CSNET library.

Errors codes smaller than -200 are internal error codes.

Enumerator
SCION_ERR_GENERIC	Something went wrong.
SCION_ERR_MEM_ALLOC_FAIL	Memory allocation failed.
SCION_ERR_NO_PATHS	No paths to the destination were found.
SCION_ERR_BUF_TOO_SMALL	The buffer provided was not large enough.
SCION_ERR_ADDR_FAMILY_UNKNOWN	Encountered an unsupported address family. See also scion_addr_family
SCION_ERR_MAX_HDR_LEN_EXCEEDED	Could not send the packet because the maximum SCION header length was exceeded.
SCION_ERR_FILE_NOT_FOUND	The file provided was not found.
SCION_ERR_TOPOLOGY_INVALID	The topology is invalid.
SCION_ERR_ADDR_FAMILY_MISMATCH	The provided address has an incompatible address family. This can happen when binding an address that has a different address family than the socket, or when sending/connecting to a host in the same AS that has a different address family than the socket.
SCION_ERR_NETWORK_ADDR_FAMILY_MISMATCH	The provided network has a different address family than the socket.
SCION_ERR_PROTO_UNKNOWN	The protocol is not supported. See also scion_proto
SCION_ERR_NOT_CONNECTED	The socket is not connected yet.
SCION_ERR_DST_MISMATCH	The path destination IA does not match the destination IA.
SCION_ERR_INVALID_ISD_AS_STR	The provided IA string is invalid.
SCION_ERR_WOULD_BLOCK	The receive operation is in non-blocking mode and there is nothing to receive.
SCION_ERR_ADDR_INVALID	The provided address is invalid.
SCION_ERR_ALREADY_BOUND	The socket is already bound.
SCION_ERR_FLAG_NOT_IMPLEMENTED	The flag is not implemented by the library.
SCION_ERR_FLAG_NOT_SUPPORTED	The flag is not supported by the OS.
SCION_ERR_SEND_FAIL	Encountered an unexpected error when sending packets.
SCION_ERR_RECV_FAIL	Encountered an unexpected error when receiving packets.
SCION_ERR_ADDR_IN_USE	The address is already in use. See also EADDRINUSE
SCION_ERR_ADDR_NOT_AVAILABLE	The address is not available. See also EADDRNOTAVAIL
SCION_ERR_OUTPUT_QUEUE_FULL	The socket output queue is already full. See also ENOBUFS
SCION_ERR_SOCK_OPT_INVALID	The provided socket option is invalid.
SCION_ERR_ADDR_BUF_TOO_SMALL	The provided address buffer is too small.
SCION_ERR_PATH_EXPIRED	The path has expired and needs to be refreshed.
SCION_ERR_NOT_BOUND	The socket is not bound.
SCION_ERR_NETWORK_UNKNOWN	Operation cannot be performed with a networkless socket.
SCION_ERR_MSG_TOO_LARGE	The message is too large.
SCION_ERR_SRC_ADDR_UNKNOWN	The source address of the socket could not automatically be determined. It has to be provided by explicitly binding the socket to a non-wildcard address. See also Source Address Determination
SCION_ERR_BOOTSTRAPPING_FAIL	The bootstrapping process failed. Make sure the network is configured correctly.

◆ scion_addr_family

enum scion_addr_family

The address families that SCION supports.

Enumerator
SCION_AF_INET	IPv4 addresses.
SCION_AF_INET6	IPv6 addresses.

◆ scion_proto

enum scion_proto

The protocols that SCION supports.

Enumerator

SCION_PROTO_UDP

User Datagram Protocol

See also: https://en.wikipedia.org/wiki/User_Datagram_Protocol

SCION_PROTO_SCMP

SCION Control Message Protocol

See also: https://docs.scion.org/en/latest/protocols/scmp.html

◆ scion_link_type

enum scion_link_type

The linky type of a hop.

Enumerator
SCION_LINK_TYPE_UNSPECIFIED	Unspecified link type.
SCION_LINK_TYPE_DIRECT	Direct physical connection.
SCION_LINK_TYPE_MULTI_HOP	Connection with local routing/switching.
SCION_LINK_TYPE_OPEN_NET	Connection overlaid over publicly routed Internet.

◆ scion_scmp_echo_type

enum scion_scmp_echo_type

The SCMP echo message types.

Enumerator

SCION_ECHO_TYPE_REQUEST

An echo request.

See also: https://docs.scion.org/en/latest/protocols/scmp.html#echo-request

SCION_ECHO_TYPE_REPLY

An echo reply.

See also: https://docs.scion.org/en/latest/protocols/scmp.html#echo-reply

Function Documentation

◆ scion_strerror()

char * scion_strerror ( int err )

Returns the string representation of an error.

Parameters

err	A SCION error.

Returns: A string representation of the error.

◆ scion_ia_parse()

int scion_ia_parse	(	const char *	str,
		size_t	len,
		scion_ia *	ia
	)

Parses an IA string.

Parameters

[in]	str	The string.
[in]	len	The length of the string (without NULL terminator).
[out]	ia	The resulting IA.

Returns: 0 on success, a negative error code on failure.

◆ scion_ia_str()

int scion_ia_str	(	scion_ia	ia,
		char *	buf,
		size_t	buflen
	)

Gets the string representation of an IA.

Parameters

[in]	ia	The IA.
[in,out]	buf	The buffer in which the string is stored.
[in]	buflen	The length of the buffer.

Returns: 0 on success, a negative error code on failure.

See also: The macro SCION_IA_STRLEN can be used to allocate a buffer of appropriate size.

◆ scion_ia_print()

void scion_ia_print ( scion_ia ia )

Prints an IA to stdout.

Parameters

[in] ia The IA.

◆ scion_topology_from_file()

int scion_topology_from_file	(	struct scion_topology **	topology,
		const char *	path
	)

Initializes a topology from a file.

Parameters

[out]	topology	The resulting topology.
[in]	path	The path of the topology file.

Returns: 0 on success, a negative error code on failure.

◆ scion_topology_get_local_ia()

scion_ia scion_topology_get_local_ia ( struct scion_topology * topo )

Gets the IA from the topology.

Parameters

[in] topo The topology.

Returns: The IA of the topology.

◆ scion_topology_free()

void scion_topology_free ( struct scion_topology * topo )

Frees a topology.

Parameters

[in] topo The topology to free.

◆ scion_bootstrap()

int scion_bootstrap ( const char * topology_output_path )

Tries to automatically bootstrap the topology and store it.

Parameters

[in] topology_output_path The path used to store the topology file.

Returns: 0 on success, a negative error code on failure.

Note: Currently, only the DNS bootstrapping method is supported.

See also: End Host Bootstrapping - DNS

◆ scion_network()

int scion_network	(	struct scion_network **	net,
		struct scion_topology *	topology
	)

Initializes a network with a topology.

Parameters

[out]	net	The resulting network.
[in]	topology	The topology of the network.

Returns: 0 on success, a negative error code on failure.

◆ scion_network_free()

void scion_network_free ( struct scion_network * net )

Frees a network.

Parameters

[in] net The network to free.

◆ scion_network_get_local_addr_family()

enum scion_addr_family scion_network_get_local_addr_family ( struct scion_network * net )

Gets the local address family of a network.

Parameters

[in] net The network.

Returns: The local address family.

◆ scion_path_reverse()

int scion_path_reverse ( struct scion_path * path )

Reverses a path.

Parameters

[in,out] path The path to reverse.

Returns: 0 on success, a negative error code on failure.

◆ scion_path_get_numhops()

size_t scion_path_get_numhops ( const struct scion_path * path )

Gets the number of hops of a path.

Parameters

[in] path The path.

Returns: The number of hops of the path.

◆ scion_path_free()

void scion_path_free ( struct scion_path * path )

Frees a path.

Parameters

[in] path The path to free.

◆ scion_path_get_metadata()

const struct scion_path_metadata * scion_path_get_metadata ( const struct scion_path * path )

Gets the metadata of a path.

Parameters

[in] path The path.

Returns: A reference to the metadata of the path.

Note: Do not modify the metadata.

◆ scion_path_print()

void scion_path_print ( const struct scion_path * path )

Prints a path to stdout.

Parameters

[in] path The path to print.

◆ scion_path_print_metadata()

void scion_path_print_metadata ( const struct scion_path * path )

Prints the metadata of a path.

Parameters

[in] path The path.

◆ scion_path_collection_free()

void scion_path_collection_free ( struct scion_path_collection * paths )

Frees a collection of paths, including the paths themselves.

Parameters

[in] paths The path collection.

◆ scion_path_collection_find()

struct scion_path * scion_path_collection_find	(	struct scion_path_collection *	paths,
		struct scion_path_predicate	predicate
	)

Finds the first path that matches the provided predicate.

Parameters

[in]	paths	The path collection.
[in]	predicate	The predicate.

Returns: The first path that matches, or NULL if no path matched.

See also: scion_path_predicate

◆ scion_path_collection_pop()

struct scion_path * scion_path_collection_pop ( struct scion_path_collection * paths )

Gets and removes the first element from a path collection.

Parameters

[in] paths The path collection.

Returns: The first element of the path collection, or NULL if the path collection is empty.

Note: The returned element must be freed by the caller.

◆ scion_path_collection_first()

struct scion_path * scion_path_collection_first ( struct scion_path_collection * paths )

Gets the first element of a path collection.

Parameters

[in] paths The path collection.

Returns: The first element of the path collection, or NULL if the path collection is empty.

Note: The returned element must not be freed by the caller.

◆ scion_path_collection_sort()

void scion_path_collection_sort	(	struct scion_path_collection *	paths,
		struct scion_path_comparator	comparator
	)

Sorts a path collection in-place with the provided comparator.

Parameters

[in,out]	paths	The path collection.
[in]	comparator	The comparator.

See also: scion_path_comparator

◆ scion_path_collection_filter()

void scion_path_collection_filter	(	struct scion_path_collection *	paths,
		struct scion_path_predicate	predicate
	)

Filters a path collection in-place with the provided predicate.

Parameters

[in,out]	paths	The path collection.
[in]	predicate	The predicate.

See also: scion_path_predicate

◆ scion_path_collection_size()

size_t scion_path_collection_size ( struct scion_path_collection * paths )

Gets the number of paths in a path collection.

Parameters

[in] paths The path collection.

Returns: The number of paths in the path collection.

◆ scion_path_collection_as_array()

struct scion_path ** scion_path_collection_as_array	(	struct scion_path_collection *	paths,
		size_t *	len
	)

Creates an array representation of a path collection.

Parameters

[in]	paths	The path collection.
[out]	len	The length of the array.

Returns: The array representation of the path collection.

Note: The array must be freed by the caller. Do not free the path entries.

◆ scion_path_collection_print()

void scion_path_collection_print ( struct scion_path_collection * paths )

Prints a path collection to stdout.

Parameters

[in] paths The path list to print.

◆ scion_path_collection_fetch()

int scion_path_collection_fetch	(	struct scion_network *	network,
		scion_ia	dst,
		uint	opt,
		struct scion_path_collection **	paths
	)

Fetches the paths from the local SCION network to the destination IA.

Parameters

[in]	network	The local network.
[in]	dst	The destination IA.
[in]	opt	Optional path finding options.
[out]	paths	The collection of paths found.

Returns: 0 on success, a negative error code on failure.

◆ scion_policy_min_mtu()

struct scion_policy scion_policy_min_mtu ( uint32_t * mtu )

Returns a policy that ensures all paths have the provided minimum MTU.

Parameters

[in] mtu The minimum MTU.

Returns: The path policy.

◆ scion_socket()

int scion_socket	(	struct scion_socket **	scion_sock,
		enum scion_addr_family	addr_family,
		enum scion_proto	protocol,
		struct scion_network *	network
	)

Initializes a SCION socket.

Parameters

[out]	scion_sock	The resulting SCION socket.
[in]	addr_family	The address family to use.
[in]	protocol	The protocol to use.
[in]	network	The network to use. If NULL, the socket is in networkless mode. Networkless sockets cannot be connected, must always be bound manually before sending and always need an explicit path when sending.

Returns: 0 on success, a negative error code on failure.

◆ scion_bind()

int scion_bind	(	struct scion_socket *	scion_sock,
		const struct sockaddr *	addr,
		socklen_t	addrlen
	)

Binds a SCION socket to an address.

Parameters

[in,out]	scion_sock	The socket to bind.
[in]	addr	The address to bind.
[in]	addrlen	The length of the address.

Returns: 0 on success, a negative error code on failure.

◆ scion_connect()

int scion_connect	(	struct scion_socket *	scion_sock,
		const struct sockaddr *	addr,
		socklen_t	addrlen,
		scion_ia	ia
	)

Connects a SCION socket to an address.

Parameters

[in,out]	scion_sock	The socket to connect.
[in]	addr	The address to connect to.
[in]	addrlen	The length of the address.
[in]	ia	The IA to connect to.

Returns: 0 on success, a negative error code on failure.

Note: Cannot be used with networkless sockets.

◆ scion_send()

ssize_t scion_send	(	struct scion_socket *	scion_sock,
		const void *	buf,
		size_t	size,
		int	flags
	)

Sends a packet to the connected destination of the SCION socket.

Parameters

[in,out]	scion_sock	The connected socket to use.
[in]	buf	The data to send.
[in]	size	The size of the data.
[in]	flags	The send flags to use. Must be 0 if no flags should be used.

Returns: The amount of data sent on success, a negative error code on failure.

Note: The currently supported send flags are MSG_CONFIRM, MSG_DONTWAIT and MSG_MORE.; Is equivalent to scion_sendto(scion_sock, buf, size, flags, NULL, 0, 0, NULL).

◆ scion_sendto()

ssize_t scion_sendto	(	struct scion_socket *	scion_sock,
		const void *	buf,
		size_t	size,
		int	flags,
		const struct sockaddr *	dst_addr,
		socklen_t	addrlen,
		scion_ia	dst_ia,
		struct scion_path *	path
	)

Sends a packet to a destination.

Parameters

[in,out]	scion_sock	The socket.
[in]	buf	The data to send.
[in]	size	The size of the data.
[in]	flags	The send flags to use. Must be 0 if no flags should be used.
[in]	dst_addr	The destination address. If NULL, the connected destination address is used.
[in]	addrlen	The length of the destination address. Must be 0 if dst_addr is NULL.
[in]	dst_ia	The destination IA. Must be 0 if dst_addr is NULL.
[in]	path	The path to use. If NULL, a suitable path is automatically used.

Returns: The amount of data sent on success, a negative error code on failure.

Note: The currently supported send flags are MSG_CONFIRM, MSG_DONTWAIT and MSG_MORE.; If a networkless socket is used, the path must be provided explicitly.

◆ scion_recv()

ssize_t scion_recv	(	struct scion_socket *	scion_sock,
		void *	buf,
		size_t	size,
		int	flags
	)

Receives a packet on the SCION socket.

Parameters

[in,out]	scion_sock	The socket.
[out]	buf	The buffer to store the received packet.
[in,out]	size	Must contain the size of the provided data buffer when calling. Contains the size of the data received on return.
[in]	flags	The receive flags to use. Must be 0 if no flags should be used.

Returns: The amount of data received on success, a negative error code on failure.

Note: The currently supported receive flags are MSG_DONTWAIT and MSG_PEEK.; Is equivalent to scion_recvfrom(scion_sock, buf, size, flags, NULL, 0, 0, NULL).

◆ scion_recvfrom()

ssize_t scion_recvfrom	(	struct scion_socket *	scion_sock,
		void *	buf,
		size_t	size,
		int	flags,
		struct sockaddr *	src_addr,
		socklen_t *	addrlen,
		scion_ia *	src_ia,
		struct scion_path **	path
	)

Receives a packet on the SCION socket.

Parameters

[in,out]	scion_sock	The socket.
[in]	buf	The buffer to store the received packet.
[in]	size	Must contain the size of the provided data buffer when calling. Contains the size of the data received on return.
[in]	flags	The receive flags to use. Must be 0 if no flags should be used.
[out]	src_addr	The sender address of the packet. If NULL, the path is not returned.
[in,out]	addrlen	Must contain the size of the provided address buffer when calling. Contains the size of the sender address on return.
[out]	src_ia	The sender IA. If NULL, the IA is not returned.
[out]	path	The path the packet took. If NULL, the path is not returned.

Returns: The amount of data received on success, a negative error code on failure.

Note: The currently supported receive flags are MSG_DONTWAIT and MSG_PEEK.

◆ scion_close()

int scion_close ( struct scion_socket * scion_sock )

Closes a SCION socket.

Parameters

[in,out] scion_sock The socket to close.

Returns: 0 on success, a negative error code on failure.

◆ scion_getsockopt()

int scion_getsockopt	(	struct scion_socket *	scion_sock,
		int	level,
		int	optname,
		void *	optval,
		socklen_t *	optlen
	)

Gets a SCION socket option.

Parameters

[in]	scion_sock	The socket.
[in]	level	The option level.
[in]	optname	The option name.
[out]	optval	The option value buffer.
[in,out]	optlen	Must contain the size of the option value buffer when calling. Contains the effective size of the option value on return.

Returns: 0 on success, a negative error code on failure.

Note: Directly gets a socket option on the underlying system socket. Additionally, supports the socket level option SCION_SO_DEBUG, which allows for better debugging.

◆ scion_setsockopt()

int scion_setsockopt	(	struct scion_socket *	scion_sock,
		int	level,
		int	optname,
		const void *	optval,
		socklen_t	optlen
	)

Sets a SCION socket option.

Parameters

[in,out]	scion_sock	The socket.
[in]	level	The option level.
[in]	optname	The option name.
[in]	optval	The option value buffer.
[in]	optlen	The option value buffer length.

Returns: 0 on success, a negative error code on failure.

Note: Directly sets a socket option on the underlying system socket. Additionally, supports the socket level option SCION_SO_DEBUG, which allows for better debugging.

◆ scion_getsockname()

int scion_getsockname	(	struct scion_socket *	scion_sock,
		struct sockaddr *	addr,
		socklen_t *	addrlen,
		scion_ia *	ia
	)

Gets the address of a SCION socket.

Parameters

[in]	scion_sock	The socket.
[out]	addr	The address of the socket. If NULL, the address is not returned.
[in,out]	addrlen	Must contain the size of the address buffer when calling. Contains the effective size of the address on return.
[out]	ia	The IA of the socket. If NULL, the IA is not returned.

Returns: 0 on success, a negative error code on failure.

Note: If a networkless socket is used, the IA must be NULL.

◆ scion_getsockfd()

int scion_getsockfd	(	struct scion_socket *	scion_sock,
		int *	fd
	)

Gets the file descriptor of the underlying system socket.

Parameters

[in]	scion_sock	The socket.
[out]	fd	The file descriptor of the underlying system socket.

Returns: 0 on success, a negative error code on failure.

◆ scion_setsockerrcb()

int scion_setsockerrcb	(	struct scion_socket *	scion_sock,
		scion_socket_scmp_error_cb	cb,
		void *	ctx
	)

Sets the SCMP error callback that is called when a SCMP error is received by the socket.

Parameters

[in,out]	scion_sock	The socket.
[in]	cb	The callback to use.
[in]	ctx	The user-defined context that is passed to every invocation of the callback. Can be NULL.

Returns: 0 on success, a negative error code on failure.

◆ scion_setsockpolicy()

int scion_setsockpolicy	(	struct scion_socket *	scion_sock,
		struct scion_policy	policy
	)

Sets the path selection policy of a socket.

Parameters

scion_sock	The socket.
policy	The path selection policy to use.

Returns: 0 on success, a negative error code on failure.

◆ scion_addr_print()

void scion_addr_print	(	const struct sockaddr *	addr,
		scion_ia	ia
	)

Prints a SCION address pair to stdout.

Parameters

[in]	addr	The address.
[in]	ia	The IA.

◆ scion_scmp_get_type()

uint8_t scion_scmp_get_type	(	const uint8_t *	buf,
		uint16_t	buf_len
	)

Gets the type of a SCMP message.

Parameters

[in]	buf	The serialized SCMP message.
[in]	buf_len	The length of the SCMP message.

Returns: The type of the SCMP message.

See also: https://docs.scion.org/en/latest/protocols/scmp.html#types

◆ scion_scmp_get_code()

uint8_t scion_scmp_get_code	(	const uint8_t *	buf,
		uint16_t	buf_len
	)

Gets the code of a SCMP message.

Parameters

[in]	buf	The serialized SCMP messsage.
[in]	buf_len	The length of the SCMP message.

Returns: The code of the SCMP message.

◆ scion_scmp_is_error()

bool scion_scmp_is_error	(	const uint8_t *	buf,
		uint16_t	buf_len
	)

Determines whether the SCMP message is an error message.

Parameters

[in]	buf	The serialized SCMP message.
[in]	buf_len	The length of the serialized SCMP message.

Returns: true if the SCMP message is an error message, false otherwise.

See also: https://docs.scion.org/en/latest/protocols/scmp.html#types

◆ scion_scmp_echo_len()

uint16_t scion_scmp_echo_len ( struct scion_scmp_echo * scmp_echo )

Determines how large the serialized SCMP echo message will be.

Parameters

[in] scmp_echo The SCMP echo message.

Returns: the size of the serialized SCMP echo message in bytes.

◆ scion_scmp_echo_serialize()

int scion_scmp_echo_serialize	(	const struct scion_scmp_echo *	scmp_echo,
		uint8_t *	buf,
		uint16_t	buf_len
	)

Serializes an SCMP echo message.

Parameters

[in]	scmp_echo	The SCMP echo message to serialize.
[out]	buf	The serialized SCMP echo message.
[in]	buf_len	The length of the serialized message.

Returns: 0 on success, a negative error code on failure.

Note: Use scion_scmp_echo_len to determine how large the buffer needs to be.

◆ scion_scmp_echo_deserialize()

int scion_scmp_echo_deserialize	(	const uint8_t *	buf,
		uint16_t	buf_len,
		struct scion_scmp_echo *	scmp_echo
	)

Deserializes an SCMP echo message.

Parameters

[in]	buf	The serialized SCMP echo message.
[in]	buf_len	The length of the serialized message.
[out]	scmp_echo	The SCMP echo message.

Returns: 0 on success, a negative error code on failure.

◆ scion_scmp_echo_free_members()

void scion_scmp_echo_free_members ( struct scion_scmp_echo * scmp_echo )

Frees the intrenal memebers of a SCMP echo message.

Parameters

[in] scmp_echo The SCMP echo message.

Variable Documentation

◆ scion_policy_highest_mtu

const struct scion_policy scion_policy_highest_mtu

extern

A policy that prefers paths with high MTU.

◆ scion_policy_least_hops

const struct scion_policy scion_policy_least_hops

extern

A policy that prefers paths with few hops.

◆ scion_policy_lowest_latency

const struct scion_policy scion_policy_lowest_latency

extern

A policy that prefers paths with low latency.

◆ scion_policy_highest_bandwidth

const struct scion_policy scion_policy_highest_bandwidth

extern

A policy that prefers paths with high bandwidth.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SCION_IA_STRLEN

◆ SCION_PATH_METADATA_LATENCY_IS_UNSET

◆ SCION_PATH_METADATA_BANDWIDTH_IS_UNSET

◆ SCION_PATH_METADATA_GEO_IS_UNSET

◆ SCION_PATH_METADATA_INTERNAL_HOPS_IS_UNSET

Typedef Documentation

◆ scion_ia

◆ scion_ifid

◆ scion_path_predicate_fn

◆ scion_path_comparator_fn

◆ scion_policy_fn

◆ scion_socket_scmp_error_cb

Enumeration Type Documentation

◆ scion_error

◆ scion_addr_family

◆ scion_proto

◆ scion_link_type

◆ scion_scmp_echo_type

Function Documentation

◆ scion_strerror()

◆ scion_ia_parse()

◆ scion_ia_str()

◆ scion_ia_print()

◆ scion_topology_from_file()

◆ scion_topology_get_local_ia()

◆ scion_topology_free()

◆ scion_bootstrap()

◆ scion_network()

◆ scion_network_free()

◆ scion_network_get_local_addr_family()

◆ scion_path_reverse()

◆ scion_path_get_numhops()

◆ scion_path_free()

◆ scion_path_get_metadata()

◆ scion_path_print()

◆ scion_path_print_metadata()

◆ scion_path_collection_free()

◆ scion_path_collection_find()

◆ scion_path_collection_pop()

◆ scion_path_collection_first()

◆ scion_path_collection_sort()

◆ scion_path_collection_filter()

◆ scion_path_collection_size()

◆ scion_path_collection_as_array()

◆ scion_path_collection_print()

◆ scion_path_collection_fetch()

◆ scion_policy_min_mtu()

◆ scion_socket()

◆ scion_bind()

◆ scion_connect()

◆ scion_send()

◆ scion_sendto()

◆ scion_recv()

◆ scion_recvfrom()

◆ scion_close()

◆ scion_getsockopt()

◆ scion_setsockopt()

◆ scion_getsockname()

◆ scion_getsockfd()

◆ scion_setsockerrcb()

◆ scion_setsockpolicy()

◆ scion_addr_print()

◆ scion_scmp_get_type()

◆ scion_scmp_get_code()

◆ scion_scmp_is_error()

◆ scion_scmp_echo_len()

◆ scion_scmp_echo_serialize()

◆ scion_scmp_echo_deserialize()

◆ scion_scmp_echo_free_members()

Variable Documentation

◆ scion_policy_highest_mtu

◆ scion_policy_least_hops