Socket convenience functions

## Files

file | socket.h
file | socket.c

## Macros

#define | OSMO_SOCK_F_CONNECT (1 << 0)
| connect the socket to a remote peer More...
#define | OSMO_SOCK_F_BIND (1 << 1)
| bind the socket to a local address/port More...
#define | OSMO_SOCK_F_NONBLOCK (1 << 2)
| switch socket to non-blocking mode More...
#define | OSMO_SOCK_F_NO_MCAST_LOOP (1 << 3)
| disable multiast loop (IP_MULTICAST_LOOP) More...
#define | OSMO_SOCK_F_NO_MCAST_ALL (1 << 4)
| disable receiving all multiast even for non-subscribed groups More...

## Functions

int | osmo_sock_init (uint16_t family, uint16_t type, uint8_t proto, const char *host, uint16_t port, unsigned int flags)
| Initialize a socket (including bind/connect) More...
int | osmo_sock_init2 (uint16_t family, uint16_t type, uint8_t proto, const char *local_host, uint16_t local_port, const char *remote_host, uint16_t remote_port, unsigned int flags)
| Initialize a socket (including bind and/or connect) More...
int | osmo_sock_init_ofd (struct osmo_fd *ofd, int family, int type, int proto, const char *host, uint16_t port, unsigned int flags)
| Initialize a socket and fill osmo_fd. More...
int | osmo_sock_init2_ofd (struct osmo_fd *ofd, int family, int type, int proto, const char *local_host, uint16_t local_port, const char *remote_host, uint16_t remote_port, unsigned int flags)
| Initialize a socket and fill osmo_fd. More...
int | osmo_sock_init_sa (struct sockaddr *ss, uint16_t type, uint8_t proto, unsigned int flags)
| Initialize a socket and fill sockaddr. More...
int | osmo_sockaddr_is_local (struct sockaddr *addr, unsigned int addrlen)
| Determine if the given address is a local address. More...
unsigned int | osmo_sockaddr_to_str_and_uint (char *addr, unsigned int addr_len, uint16_t *port, const struct sockaddr *sa)
| Convert sockaddr to IP address as char string and port as uint16_t. More...
int | osmo_sock_unix_init (uint16_t type, uint8_t proto, const char *socket_path, unsigned int flags)
| Initialize a unix domain socket (including bind/connect) More...
int | osmo_sock_unix_init_ofd (struct osmo_fd *ofd, uint16_t type, uint8_t proto, const char *socket_path, unsigned int flags)
| Initialize a unix domain socket and fill osmo_fd. More...
char * | osmo_sock_get_name (void *ctx, int fd)
| Get address/port information on soocket in dyn-alloc string. More...
int | osmo_sock_mcast_loop_set (int fd, bool enable)
| Activate or de-activate local loop-back of transmitted multicast packets. More...
int | osmo_sock_mcast_ttl_set (int fd, uint8_t ttl)
| Set the TTL of outbound multicast packets. More...
int | osmo_sock_mcast_all_set (int fd, bool enable)
| Enable/disable receiving all multicast packets, even for non-subscribed groups. More...
int | osmo_sock_mcast_subscribe (int fd, const char *grp_addr)
| Subscribe to the given IP multicast group. More...
int | osmo_sock_local_ip (char *local_ip, const char *remote_ip)
| Determine the matching local IP-address for a given remote IP-Address. More...
static struct addrinfo * | addrinfo_helper (uint16_t family, uint16_t type, uint8_t proto, const char *host, uint16_t port, bool passive)
static int | socket_helper (const struct addrinfo *rp, unsigned int flags)
static int | osmo_sock_init_tail (int fd, uint16_t type, unsigned int flags)
static int | osmo_fd_init_ofd (struct osmo_fd *ofd, int sfd)
| fill osmo_fd for a give sfd More...
static int | sockaddr_equal (const struct sockaddr *a, const struct sockaddr *b, unsigned int len)
static int | sock_get_domain (int fd)

## Detailed Description

Osmocom socket convenience functions.

## Macro Definition Documentation

## OSMO_SOCK_F_BIND

#define OSMO_SOCK_F_BIND (1 << 1)

bind the socket to a local address/port

## OSMO_SOCK_F_CONNECT

#define OSMO_SOCK_F_CONNECT (1 << 0)

connect the socket to a remote peer

## OSMO_SOCK_F_NO_MCAST_ALL

#define OSMO_SOCK_F_NO_MCAST_ALL (1 << 4)

disable receiving all multiast even for non-subscribed groups

## OSMO_SOCK_F_NO_MCAST_LOOP

#define OSMO_SOCK_F_NO_MCAST_LOOP (1 << 3)

disable multiast loop (IP_MULTICAST_LOOP)

## OSMO_SOCK_F_NONBLOCK

#define OSMO_SOCK_F_NONBLOCK (1 << 2)

switch socket to non-blocking mode

## Function Documentation

## addrinfo_helper()

static struct addrinfo* addrinfo_helper | ( | uint16_t | family,
|  | uint16_t | type,
|  | uint8_t | proto,
|  | const char * | host,
|  | uint16_t | port,
|  | bool | passive
| ) |  |

static

References DLGLOBAL, LOGL_ERROR, LOGP, and type.

Referenced by osmo_sock_init(), and osmo_sock_init2().

## osmo_fd_init_ofd()

static int osmo_fd_init_ofd | ( | struct osmo_fd * | ofd,
|  | int | sfd
| ) |  |

inline static

fill osmo_fd for a give sfd

Parameters

  [out] | ofd | file descriptor (will be filled in)
  [in] | sfd | socket file descriptor

Returns
  socket fd on success; negative on error

This function fills the ofd structure.

References BSC_FD_READ, osmo_fd::fd, osmo_fd_register(), and osmo_fd::when.

Referenced by osmo_sock_init2_ofd(), osmo_sock_init_ofd(), and osmo_sock_unix_init_ofd().

## osmo_sock_get_name()

char * osmo_sock_get_name | ( | void * | ctx,
|  | int | fd
| ) |  |

Get address/port information on soocket in dyn-alloc string.

Parameters

  [in] | ctx | talloc context from which to allocate string buffer
  [in] | fd | file descriptor of socket

Returns
  string identifying the connection of this socket

## osmo_sock_init()

int osmo_sock_init | ( | uint16_t | family,
|  | uint16_t | type,
|  | uint8_t | proto,
|  | const char * | host,
|  | uint16_t | port,
|  | unsigned int | flags
| ) |  |

Initialize a socket (including bind/connect)

Parameters

  [in] | family | Address Family like AF_INET, AF_INET6, AF_UNSPEC
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | host | remote host name or IP address in string form
  [in] | port | remote port number in host byte order
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket file descriptor on success; negative on error

This function creates a new socket of the designated family, type and proto and optionally binds or connects it, depending on the value of flags parameter.

References addrinfo_helper(), DLGLOBAL, LOGL_ERROR, LOGP, OSMO_SOCK_F_BIND, OSMO_SOCK_F_CONNECT, osmo_sock_init_tail(), socket_helper(), and type.

Referenced by gsmtap_source_init_fd(), osmo_sock_init_ofd(), and osmo_sock_init_sa().

## osmo_sock_init2()

int osmo_sock_init2 | ( | uint16_t | family,
|  | uint16_t | type,
|  | uint8_t | proto,
|  | const char * | local_host,
|  | uint16_t | local_port,
|  | const char * | remote_host,
|  | uint16_t | remote_port,
|  | unsigned int | flags
| ) |  |

Initialize a socket (including bind and/or connect)

Parameters

  [in] | family | Address Family like AF_INET, AF_INET6, AF_UNSPEC
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | local_host | local host name or IP address in string form
  [in] | local_port | local port number in host byte order
  [in] | remote_host | remote host name or IP address in string form
  [in] | remote_port | remote port number in host byte order
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket file descriptor on success; negative on error

This function creates a new socket of the designated family, type and proto and optionally binds it to the local_host and local_port as well as optionally connects it to the remote_host and \q remote_port, depending on the value * of flags parameter.

As opposed to osmo_sock_init(), this function allows to combine the OSMO_SOCK_F_BIND and OSMO_SOCK_F_CONNECT flags. This is useful if you want to connect to a remote host/port, but still want to bind that socket to either a specific local alias IP and/or a specific local source port.

You must specify either OSMO_SOCK_F_BIND, or OSMO_SOCK_F_CONNECT, or both.

If OSMO_SOCK_F_NONBLOCK is specified, the socket will be set to non-blocking mode.

References addrinfo_helper(), DLGLOBAL, LOGL_ERROR, LOGP, OSMO_SOCK_F_BIND, OSMO_SOCK_F_CONNECT, osmo_sock_init_tail(), socket_helper(), and type.

Referenced by osmo_sock_init2_ofd(), and osmo_sock_local_ip().

## osmo_sock_init2_ofd()

int osmo_sock_init2_ofd | ( | struct osmo_fd * | ofd,
|  | int | family,
|  | int | type,
|  | int | proto,
|  | const char * | local_host,
|  | uint16_t | local_port,
|  | const char * | remote_host,
|  | uint16_t | remote_port,
|  | unsigned int | flags
| ) |  |

Initialize a socket and fill osmo_fd.

Parameters

  [out] | ofd | file descriptor (will be filled in)
  [in] | family | Address Family like AF_INET, AF_INET6, AF_UNSPEC
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | local_host | local host name or IP address in string form
  [in] | local_port | local port number in host byte order
  [in] | remote_host | remote host name or IP address in string form
  [in] | remote_port | remote port number in host byte order
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket fd on success; negative on error

This function creates (and optionall binds/connects) a socket using osmo_sock_init2, but also fills the ofd structure.

References osmo_fd_init_ofd(), osmo_sock_init2(), and type.

## osmo_sock_init_ofd()

int osmo_sock_init_ofd | ( | struct osmo_fd * | ofd,
|  | int | family,
|  | int | type,
|  | int | proto,
|  | const char * | host,
|  | uint16_t | port,
|  | unsigned int | flags
| ) |  |

Initialize a socket and fill osmo_fd.

Parameters

  [out] | ofd | file descriptor (will be filled in)
  [in] | family | Address Family like AF_INET, AF_INET6, AF_UNSPEC
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | host | remote host name or IP address in string form
  [in] | port | remote port number in host byte order
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket fd on success; negative on error

This function creates (and optionall binds/connects) a socket using osmo_sock_init, but also fills the ofd structure.

References osmo_fd_init_ofd(), osmo_sock_init(), and type.

## osmo_sock_init_sa()

int osmo_sock_init_sa | ( | struct sockaddr * | ss,
|  | uint16_t | type,
|  | uint8_t | proto,
|  | unsigned int | flags
| ) |  |

Initialize a socket and fill sockaddr.

Parameters

  [out] | ss | socket address (will be filled in)
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket fd on success; negative on error

This function creates (and optionall binds/connects) a socket using osmo_sock_init, but also fills the ss structure.

References DLGLOBAL, LOGL_ERROR, LOGP, osmo_sock_init(), and type.

Referenced by gsmtap_source_add_sink_fd().

## osmo_sock_init_tail()

static int osmo_sock_init_tail | ( | int | fd,
|  | uint16_t | type,
|  | unsigned int | flags
| ) |  |

static

References DLGLOBAL, LOGL_ERROR, LOGP, OSMO_SOCK_F_BIND, OSMO_SOCK_F_CONNECT, OSMO_SOCK_F_NO_MCAST_ALL, OSMO_SOCK_F_NO_MCAST_LOOP, osmo_sock_mcast_all_set(), osmo_sock_mcast_loop_set(), and type.

Referenced by osmo_sock_init(), osmo_sock_init2(), and osmo_sock_unix_init().

## osmo_sock_local_ip()

int osmo_sock_local_ip | ( | char * | local_ip,
|  | const char * | remote_ip
| ) |  |

Determine the matching local IP-address for a given remote IP-Address.

Parameters

  [out] | local_ip | caller provided memory for resulting local IP-address
  [in] | remote_ip | remote IP-address
  [in] | fd | file descriptor of related scoket

Returns
  0 on success; negative otherwise

The function accepts IPv4 and IPv6 address strings. The caller must provide at least INET6_ADDRSTRLEN bytes for local_ip if an IPv6 is expected as as result. For IPv4 addresses the required amount is INET_ADDRSTRLEN.

References OSMO_SOCK_F_CONNECT, and osmo_sock_init2().

## osmo_sock_mcast_all_set()

int osmo_sock_mcast_all_set | ( | int | fd,
|  | bool | enable
| ) |  |

Enable/disable receiving all multicast packets, even for non-subscribed groups.

Parameters

  [in] | fd | file descriptor of related socket
  [in] | enable | Enable or Disable receiving of all packets

Returns
  0 on success; negative otherwise

References sock_get_domain().

Referenced by osmo_sock_init_tail().

## osmo_sock_mcast_loop_set()

int osmo_sock_mcast_loop_set | ( | int | fd,
|  | bool | enable
| ) |  |

Activate or de-activate local loop-back of transmitted multicast packets.

Parameters

  [in] | fd | file descriptor of related socket
  [in] | enable | Enable (true) or disable (false) loop-back

Returns
  0 on success; negative otherwise

References sock_get_domain().

Referenced by osmo_sock_init_tail().

## osmo_sock_mcast_subscribe()

int osmo_sock_mcast_subscribe | ( | int | fd,
|  | const char * | grp_addr
| ) |  |

Subscribe to the given IP multicast group.

Parameters

  [in] | fd | file descriptor of related scoket
  [in] | grp_addr | ASCII representation of the multicast group address

Returns
  0 on success; negative otherwise

References sock_get_domain().

## osmo_sock_mcast_ttl_set()

int osmo_sock_mcast_ttl_set | ( | int | fd,
|  | uint8_t | ttl
| ) |  |

Set the TTL of outbound multicast packets.

Parameters

  [in] | fd | file descriptor of related socket
  [in] | ttl | TTL of to-be-sent multicast packets

Returns
  0 on success; negative otherwise

References sock_get_domain().

## osmo_sock_unix_init()

int osmo_sock_unix_init | ( | uint16_t | type,
|  | uint8_t | proto,
|  | const char * | socket_path,
|  | unsigned int | flags
| ) |  |

Initialize a unix domain socket (including bind/connect)

Parameters

  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | socket_path | path to identify the socket
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket fd on success; negative on error

This function creates a new unix domain socket, type and proto and optionally binds or connects it, depending on the value of flags parameter.

References DLGLOBAL, LOGL_ERROR, LOGP, OSMO_SOCK_F_BIND, OSMO_SOCK_F_CONNECT, OSMO_SOCK_F_NONBLOCK, osmo_sock_init_tail(), and type.

Referenced by osmo_sock_unix_init_ofd().

## osmo_sock_unix_init_ofd()

int osmo_sock_unix_init_ofd | ( | struct osmo_fd * | ofd,
|  | uint16_t | type,
|  | uint8_t | proto,
|  | const char * | socket_path,
|  | unsigned int | flags
| ) |  |

Initialize a unix domain socket and fill osmo_fd.

Parameters

  [out] | ofd | file descriptor (will be filled in)
  [in] | type | Socket type like SOCK_DGRAM, SOCK_STREAM
  [in] | proto | Protocol like IPPROTO_TCP, IPPROTO_UDP
  [in] | socket_path | path to identify the socket
  [in] | flags | flags like OSMO_SOCK_F_CONNECT

Returns
  socket fd on success; negative on error

This function creates (and optionall binds/connects) a socket using osmo_sock_unix_init, but also fills the ofd structure.

References osmo_fd_init_ofd(), osmo_sock_unix_init(), and type.

## osmo_sockaddr_is_local()

int osmo_sockaddr_is_local | ( | struct sockaddr * | addr,
|  | unsigned int | addrlen
| ) |  |

Determine if the given address is a local address.

Parameters

  [in] | addr | Socket Address
  [in] | addrlen | Length of socket address in bytes

Returns
  1 if address is local, 0 otherwise.

References DLGLOBAL, LOGL_ERROR, LOGP, and sockaddr_equal().

Referenced by gsmtap_source_add_sink_fd().

## osmo_sockaddr_to_str_and_uint()

unsigned int osmo_sockaddr_to_str_and_uint | ( | char * | addr,
|  | unsigned int | addr_len,
|  | uint16_t * | port,
|  | const struct sockaddr * | sa
| ) |  |

Convert sockaddr to IP address as char string and port as uint16_t.

Parameters

  [out] | addr | String buffer to write IP address to, or NULL.
  [out] | addr_len | Size of addr.
  [out] | port | Pointer to uint16_t to write the port number to, or NULL.
  [in] | sa | Sockaddr to convert.

Returns
  the required string buffer size, like osmo_strlcpy(), or 0 if addr is NULL.

References osmo_strlcpy().

## sock_get_domain()

static int sock_get_domain | ( | int | fd | ) |

static

Referenced by osmo_sock_mcast_all_set(), osmo_sock_mcast_loop_set(), osmo_sock_mcast_subscribe(), and osmo_sock_mcast_ttl_set().

## sockaddr_equal()

static int sockaddr_equal | ( | const struct sockaddr * | a,
|  | const struct sockaddr * | b,
|  | unsigned int | len
| ) |  |

static

Referenced by osmo_sockaddr_is_local().

## socket_helper()

static int socket_helper | ( | const struct addrinfo * | rp,
|  | unsigned int | flags
| ) |  |

static

References DLGLOBAL, LOGL_ERROR, LOGP, and OSMO_SOCK_F_NONBLOCK.

Referenced by osmo_sock_init(), and osmo_sock_init2().