# include/sys/socket.h File Reference

`#include <netinet/in.h>`
`#include <event.h>`

## Data Structures
struct | sockaddr_in6
struct | udp_recvfrom
struct | tcp_event
## Defines
#define | _SOCKET_H 1
#define | s6_addr in6_u.u6_addr8
#define | s6_addr16 in6_u.u6_addr16
#define | s6_addr32 in6_u.u6_addr32
## Typedefs
typedef struct sockaddr_in6 | sockaddr_in6_t
typedef struct udp_recvfrom | udp_recvfrom_t
typedef struct tcp_event | tcp_event_t
## Enumerations
enum | SockTypeEnums { SOCK_STREAM = 1, SOCK_DGRAM, SOCK_DGRAM_FRAG }
enum | AFEnums { AF_INET = 10, AF_INET6 }
enum | TcpStatesEnum { ACCEPT = 1, CONNECTED, RECV, CLOSED }
## Functions
int16_t | socket (int16_t domain, int16_t type, int16_t protocol)
int16_t | send (int16_t s, const void *buf, int16_t len, int16_t flags)
int16_t | sendto (int16_t s, const void *buf, int16_t len, int16_t flags, const sockaddr_in6_t *to)
int16_t | udpbind (int16_t s, const sockaddr_in6_t *my_addr, void *buf, int16_t buflen, void(*recvfrom)(event_t event, void *cbargs, void *context), udp_recvfrom_t *recvfrom_cbargs, void *context)
int16_t | tcpbind (int16_t s, const sockaddr_in6_t *my_addr, void *buf, int16_t buflen, void(*tcp_handler)(event_t event, void *cbargs, void *context), tcp_event_t *tcp_event, void *context)
int16_t | connect (int16_t s, const sockaddr_in6_t *to)
int16_t | accept (int16_t s, const sockaddr_in6_t *to)

## Define Documentation

#define _SOCKET_H 1

#define s6_addr in6_u.u6_addr8

#define s6_addr16 in6_u.u6_addr16

#define s6_addr32 in6_u.u6_addr32

## Typedef Documentation

typedef struct sockaddr_in6 sockaddr_in6_t

typedef struct tcp_event tcp_event_t

typedef struct udp_recvfrom udp_recvfrom_t

## Enumeration Type Documentation

enum AFEnums

AF INET Protocol Family

Enumerator:

  AF_INET | IPv4 Internet protocols
  AF_INET6 | IPv6 Internet protocols

enum SockTypeEnums

Socket types.

Enumerator:

  SOCK_STREAM | Provides sequenced, reliable, two-way, connection-based byte streams.
  SOCK_DGRAM | Supports datagrams (connectionless, unreliable messages of a fixed maximum length bounded by link layer)
  SOCK_DGRAM_FRAG | Supports datagrams (connectionless, unreliable messages of a fixed maximum length bounded supported by link layer fragmentation.) This is not currently supported.

enum TcpStatesEnum

Enumerator:

  ACCEPT | Incoming TCP connection. addr in tcp_event_t contains the IP address of the peer initiating the connection.
  CONNECTED | TCP connection established.
  RECV | TCP connection has incoming data.
  CLOSED | TCP connection is closed.

## Function Documentation

int16_t accept | ( | int16_t | s,
|  | const sockaddr_in6_t * | to |
| ) |  |  |

A system call that accept an incoming connection on the socket referred to by the socket descriptor to an destination IP address. Only the type SOCK_STREAM is supported for this call.

Precondition:
  This call should be invoked after tcpbind() has notified that the socket has changed to the ACCEPT state.

Postcondition:
  The system will try to service the incoming connection to the destination.

Parameters:

  `[in]` | s | socket descriptor
  `[in]` | to | destination IP address

Returns:
  0 if the system agrees to make a connection. On error, -1 is returned, and errno is set appropriately.

Errors:
  EINVAL invalid argument passed

  EBUSY underlying socket is busy (already connected).

int16_t connect | ( | int16_t | s,
|  | const sockaddr_in6_t * | to |
| ) |  |  |

A system call that connects the socket referred to by the socket descriptor to an destination IP address. Only the type SOCK_STREAM is supported for this call.

This is a non-blocking connect call. Actual establishment of the connection or failure will be notified later.

Precondition:
  This call must be invoked after tcpbind().

Postcondition:
  The system tries to initiate a connection to the destination.

Parameters:

  `[in]` | s | socket descriptor
  `[in]` | to | destination IP address

Returns:
  0 if the system agrees to make a connection. On error, -1 is returned, and errno is set appropriately.

Errors:
  EINVAL invalid argument passed

  EBUSY underlying socket is busy (already connected).

int16_t send | ( | int16_t | s,
|  | const void * | buf,
|  | int16_t | len,
|  | int16_t | flags |
| ) |  |  |

A system call to send a message on a socket to another socket. The socket must be in a connected state (so that the intended recipient is known).

When completed, the system has copied buf up to len number of bytes into its internal queue for in order transmission of the byte stream.

Parameters:

  `[in]` | s | socket descriptor of the sending socket.
  `[in]` | buf | buffer that contains the message. The system will copy the message into the user provided buffer queue established in tcpbind.
  `[in]` | len | length of the message in bytes.
  `[in]` | flags | reserved for future use.

Returns:
  0 is returend on success. On error, -1 is returned, and errno is set appropriately.

Errors:
  EINVAL invalid argument passed. ESIZE no buffer space to accomodate message ENOTCONN the socket is not connected

int16_t sendto | ( | int16_t | s,
|  | const void * | buf,
|  | int16_t | len,
|  | int16_t | flags,
|  | const sockaddr_in6_t * | to |
| ) |  |  |

A system call to send a message on a socket to another socket. The socket must be in a connectionless state with the intended recipient specified as an argument.

When completed, the system has copied buf up to len number of bytes into its internal queue for transmission.

Parameters:

  `[in]` | s | socket descriptor of the sending socket.
  `[in]` | buf | buffer that contains the message. The system will copy the message into the user provided buffer queue established in udpbind.
  `[in]` | len | length of the message in bytes.
  `[in]` | flags | reserved for future use.
  `[in]` | to | recipient address in socket address structure

Returns:
  On error, -1 is returned, and errno is set appropriately.

Errors:
  EINVAL invalid argument passed. ESIZE no buffer space to accomodate message at this time.

int16_t socket | ( | int16_t | domain,
|  | int16_t | type,
|  | int16_t | protocol |
| ) |  |  |

A system call to create an endpoint for communication and return a descriptor if the total limit has not been reached.

Parameters:

  `[in]` | domain | specifies a communication domain or the protocol family which will be used for communication. See AFEnums.
  `[in]` | type | specifies the communication semantics. See SockTypeEnums.
  `[in]` | protocol | Not supported.

Returns:
  On success, a socket descriptor for the new socket is returned. On error, -1 is returned, and errno is set appropriately.

Errors:
  EINVAL unknown protocol, or protocol family not available.

  ENFILE the system limit on the total number of open sockets with this protocol has been reached.

int16_t tcpbind | ( | int16_t | s,
|  | const sockaddr_in6_t * | my_addr,
|  | void * | buf,
|  | int16_t | buflen,
|  | void(*)(event_t event, void *cbargs, void *context) | tcp_handler,
|  | tcp_event_t * | tcp_event,
|  | void * | context |
| ) |  |  |

A system call that gives a TCP socket the local address, a user allocated buffer for message queuing, and a callback handler for interacting with the TCP stack.

The system binds the socket s to my_addr, the corresponding callback handlers, and the user-provided heap memory for transmission queuing. Listening on the address is automatically started. These bindings will be cleared when the socket is closed.

Parameters:

  `[in]` | s | socket descriptor of the socket
  `[in]` | my_addr | local address to bind to the socket
  `[in]` | buf | user allocated heap memory to be used for buffering
  `[in]` | buflen | length of buf in bytes.
  `[in]` | tcp_handler | a callback handler to interact with the different states of a TCP session. If NULL is passed, call will fail.
  `[out]` | tcp_event | argument for the tcp_handler notification. if NULL is passed, call will fail.
  `[in]` | context | user context

Returns:
  On success, zero is returned. On error, -1 is returned and errno is set appropriately.

Errors:
  EINVAL invalid argument passed.

  EFAULT bad address.

## Callback Descriptions

### tcpbind

Parameters:

  `[in]` | event | Type is TCPBIND in EventsEnum.
  `[in]` | cbargs | is tcp_event in tcpbind().
  `[in]` | context | is context in tcpbind().

Returns:
  None.

int16_t udpbind | ( | int16_t | s,
|  | const sockaddr_in6_t * | my_addr,
|  | void * | buf,
|  | int16_t | buflen,
|  | void(*)(event_t event, void *cbargs, void *context) | recvfrom,
|  | udp_recvfrom_t * | recvfrom_cbargs,
|  | void * | context |
| ) |  |  |

A system call that gives a UDP socket the local address, a user allocated buffer for message queuing, and a callback for reception notification.

When completed, the system binds socket s to my_addr, recvfrom handler for packet reception notification and listening on the address is started automatically. These bindings will be cleared when the socket is closed.

Parameters:

  `[in]` | s | socket descriptor of the socket
  `[in]` | my_addr | local address to bind to the socket
  `[in]` | buf | user allocated heap memory to be used for buffering. (only for SOCK_DGRAM_FRAG)
  `[in]` | buflen | length of buf in bytes.(only for SOCK_DGRAM_FRAG)
  `[in]` | recvfrom | a callback handler that signals a UDP packet reception destined to my_addr. If NULL is passed, call will fail.
  `[out]` | recvfrom_cbargs | storing the recvfrom arguments for the callback. If NULL, only notification will be generated.
  `[in]` | context | user context

Returns:
  On success, zero is returned. On error, -1 is returned and errno is set appropriately.

Errors:
  EINVAL invalid argument passed.

  EFAULT bad address.

Note:
  recvfrom_cbargs needs to be copied if user wants to retain its information across callbacks.

## Callback Descriptions

### udpbind

Parameters:

  `[in]` | event | Type is UDPBIND in EventsEnum.
  `[in]` | cbargs | is recvfrom_cbargs in udpbind().
  `[in]` | context | is context in udpbind().

Returns:
  None.