bglibs: socket: General socket manipulations

bglibs

socket: General socket manipulations

## IP socket functions
int | socket_tcp4 (void)
int | socket_tcp6 (void)
int | socket_tcp (void)
int | socket_udp4 (void)
int | socket_udp6 (void)
int | socket_udp (void)
int | socket_connect4 (int sock, const ipv4addr *ip, ipv4port port)
int | socket_connect4_timeout (int sock, const ipv4addr *ip, ipv4port port, int timeout)
int | socket_connect6 (int sock, const ipv6addr *ip, ipv6port port)
int | socket_connect6_timeout (int sock, const ipv6addr *ip, ipv6port port, int timeout)
int | socket_bind4 (int sock, const ipv4addr *ip, ipv4port port)
int | socket_bind6 (int sock, const ipv6addr *ip, ipv6port port)
int | socket_accept4 (int sock, ipv4addr *ip, ipv4port *port)
int | socket_accept6 (int sock, ipv6addr *ip, ipv6port *port)
int | socket_recv4 (int sock, char *buffer, unsigned buflen, ipv4addr *ip, ipv4port *port)
int | socket_recv6 (int sock, char *buffer, unsigned buflen, ipv6addr *ip, ipv6port *port)
int | socket_send4 (int sock, const char *buffer, unsigned buflen, const ipv4addr *ip, ipv4port port)
int | socket_send6 (int sock, const char *buffer, unsigned buflen, const ipv6addr *ip, ipv6port port)
int | socket_getaddr4 (int sock, ipv4addr *ip, ipv4port *port)
int | socket_getaddr6 (int sock, ipv6addr *ip, ipv6port *port)
int | socket_cork (int sock)
int | socket_uncork (int sock)
int | socket_notcpdelay (int sock, int enable)

## UNIX local-domain socket functions
int | socket_unixdgm (void)
int | socket_unixstr (void)
int | socket_connectu (int sock, const char *path)
int | socket_connectu_timeout (int sock, const char *path, int timeout)
int | socket_bindu (int sock, const char *path)
int | socket_acceptu (int sock)
int | socket_recvu (int sock, char *buffer, unsigned buflen)
int | socket_sendu (int sock, const char *buffer, unsigned buflen)
int | socket_pairstr (int fd[2])
int | socket_pairdgm (int fd[2])

## Functions for any type of socket
int | socket_broadcast (int sock)
int | socket_connected (int sock)
int | socket_linger (int fd, int onoff, int seconds)
int | socket_listen (int sock, int backlog)
int | socket_reuse (int sock)
int | socket_shutdown (int sock, int shut_rd, int shut_wr)
int | socket_sendfd (int sock, int fd)
int | socket_recvfd (int sock)

## Detailed Description

Calling Convention

When calling a socket function, the socket file descriptor (where required) will always be the first parameter. Functions that return a file descriptor (either creating a new socket or accepting a connection on a socket return that file descriptor on success or `-1` on error. All other functions return non-zero (true) on success or `0` (false) on error. All functions set errno on error.

## Function Documentation

## ◆ socket_accept4()

int socket_accept4 | ( | int | sock,
|  | ipv4addr * | ip,
|  | ipv4port * | port
| ) |  |

Accept a connection on a socket from an IPv4 address.

References ipv4addr::addr.

## ◆ socket_accept6()

int socket_accept6 | ( | int | sock,
|  | ipv6addr * | ip,
|  | ipv6port * | port
| ) |  |

Accept a connection on a socket from an IPv6 address.

References ipv6addr::addr.

## ◆ socket_acceptu()

int socket_acceptu | ( | int | sock | ) |

Accept a UNIX domain connection.

## ◆ socket_bind4()

int socket_bind4 | ( | int | sock,
|  | const ipv4addr * | ip,
|  | ipv4port | port
| ) |  |

Bind a socket to an IPv4 address.

References ipv4addr::addr.

Referenced by dns_transmit_free(), and socket_connect4().

## ◆ socket_bind6()

int socket_bind6 | ( | int | sock,
|  | const ipv6addr * | ip,
|  | ipv6port | port
| ) |  |

Bind a socket to an IPv6 address.

References ipv6addr::addr.

## ◆ socket_bindu()

int socket_bindu | ( | int | sock,
|  | const char * | path
| ) |  |

Bind a UNIX domain address (path) to a socket.

## ◆ socket_broadcast()

int socket_broadcast | ( | int | fd | ) |

Mark a socket for broadcast transmission.

## ◆ socket_connect4()

int socket_connect4 | ( | int | sock,
|  | const ipv4addr * | ip,
|  | ipv4port | port
| ) |  |

Connect a socket to an IPv4 address.

References ipv4addr::addr, IPV4ADDR_ANY, IPV4ADDR_LOOPBACK, socket_bind4(), socket_listen(), socket_reuse(), and socket_tcp4().

Referenced by dns_transmit_free(), and socket_connect4_timeout().

## ◆ socket_connect4_timeout()

int socket_connect4_timeout | ( | int | sock,
|  | const ipv4addr * | ip,
|  | ipv4port | port,
|  | int | timeout
| ) |  |

Connect a socket to an IPv4 address, honouring a timeout.

Note
  The socket will have nonblocking mode turned on on return from this function.

References socket_connect4(), and socket_connected().

## ◆ socket_connect6()

int socket_connect6 | ( | int | sock,
|  | const ipv6addr * | ip,
|  | ipv6port | port
| ) |  |

Connect a socket to an IPv6 address.

References ipv6addr::addr.

Referenced by socket_connect6_timeout().

## ◆ socket_connect6_timeout()

int socket_connect6_timeout | ( | int | sock,
|  | const ipv6addr * | ip,
|  | ipv6port | port,
|  | int | timeout
| ) |  |

Connect a socket to an IPv6 address, honouring a timeout.

Note
  The socket will have nonblocking mode turned on on return from this function.

References socket_connect6(), and socket_connected().

## ◆ socket_connected()

int socket_connected | ( | int | sock | ) |

Test if a socket is connected.

Referenced by dns_transmit_get(), socket_connect4_timeout(), socket_connect6_timeout(), and socket_connectu_timeout().

## ◆ socket_connectu()

int socket_connectu | ( | int | sock,
|  | const char * | path
| ) |  |

Make an UNIX domain connection.

Referenced by socket_connectu_timeout().

## ◆ socket_connectu_timeout()

int socket_connectu_timeout | ( | int | sock,
|  | const char * | path,
|  | int | timeout
| ) |  |

Connect a socket to an UNIX domain address, honouring a timeout.

Note
  The socket will have nonblocking mode turned on on return from this function.

References socket_connected(), and socket_connectu().

## ◆ socket_cork()

int socket_cork | ( | int | sock | ) |

Stop a TCP socket from sending short writes.

Several UNIX OS's have a facility which can prevent packets from being sent across the wire until they are completely full, even if short writes are sent to the socket that would normally result in output packets. This routine attempts to enable that facility to optimize throughput for bulk data transfers. It is known to work on Linux (with the `TCP_CORK` option) and to at least compile on BSD (with the `TCP_NOPUSH` option). On OS's which lack either of these two options, this function is essentially a no-op.

## ◆ socket_getaddr4()

int socket_getaddr4 | ( | int | sock,
|  | ipv4addr * | addr,
|  | ipv4port * | port
| ) |  |

Determine the IPv4 address of a socket.

References ipv4addr::addr.

## ◆ socket_getaddr6()

int socket_getaddr6 | ( | int | sock,
|  | ipv6addr * | addr,
|  | ipv6port * | port
| ) |  |

Determine the IPv6 address of a socket.

References ipv6addr::addr.

## ◆ socket_linger()

int socket_linger | ( | int | fd,
|  | int | onoff,
|  | int | seconds
| ) |  |

Set the socket "linger" option.

## ◆ socket_listen()

int socket_listen | ( | int | sock,
|  | int | backlog
| ) |  |

Listen to a socket.

Referenced by socket_connect4().

## ◆ socket_notcpdelay()

int socket_notcpdelay | ( | int | fd,
|  | int | on
| ) |  |

Turn on or off TCP NODELAY flag.

Enabling NODELAY disables the standard Nagle algorithm, which tries to coalesce multiple short writes into one larger packet for better network efficiency. With NODELAY enabled, each write will immediately be sent out onto the network as a seperate packet.

## ◆ socket_pairdgm()

int socket_pairdgm | ( | int | fd[2] | ) |

Create a pair of datagram sockets.

## ◆ socket_pairstr()

int socket_pairstr | ( | int | fd[2] | ) |

Create a pair of stream sockets.

## ◆ socket_recv4()

int socket_recv4 | ( | int | sock,
|  | char * | buffer,
|  | unsigned | buflen,
|  | ipv4addr * | ip,
|  | ipv4port * | port
| ) |  |

Receive a datagram from a UDP socket.

References ipv4addr::addr.

## ◆ socket_recv6()

int socket_recv6 | ( | int | sock,
|  | char * | buffer,
|  | unsigned | buflen,
|  | ipv6addr * | ip,
|  | ipv6port * | port
| ) |  |

Receive a datagram from an IPv6 UDP socket.

References ipv6addr::addr.

## ◆ socket_recvfd()

int socket_recvfd | ( | int | sock | ) |

Receive a file descriptor over a socket.

## ◆ socket_recvu()

int socket_recvu | ( | int | sock,
|  | char * | buffer,
|  | unsigned | buflen
| ) |  |

Receive a datagram from a UNIX domain socket.

## ◆ socket_reuse()

int socket_reuse | ( | int | fd | ) |

Mark a socket for address reuse.

Referenced by socket_connect4().

## ◆ socket_send4()

int socket_send4 | ( | int | sock,
|  | const char * | buffer,
|  | unsigned | buflen,
|  | const ipv4addr * | ip,
|  | ipv4port | port
| ) |  |

Send a datagram on a UDP socket.

References ipv4addr::addr.

## ◆ socket_send6()

int socket_send6 | ( | int | sock,
|  | const char * | buffer,
|  | unsigned | buflen,
|  | const ipv6addr * | ip,
|  | ipv6port | port
| ) |  |

Send a datagram on an IPv6 UDP socket.

References ipv6addr::addr.

## ◆ socket_sendfd()

int socket_sendfd | ( | int | sock,
|  | int | fd
| ) |  |

Send a file descriptor over a socket.

## ◆ socket_sendu()

int socket_sendu | ( | int | sock,
|  | const char * | buffer,
|  | unsigned | buflen
| ) |  |

Send a datagram on a UNIX domain socket.

## ◆ socket_shutdown()

int socket_shutdown | ( | int | sock,
|  | int | shut_rd,
|  | int | shut_wr
| ) |  |

Shut down part or all of a socket.

## ◆ socket_tcp()

int socket_tcp | ( | void |  | ) |

Create a TCP/IP socket.

References socket_tcp4().

Referenced by dns_transmit_free().

## ◆ socket_tcp4()

int socket_tcp4 | ( | void |  | ) |

Create a TCP/IPv4 socket.

Referenced by socket_connect4(), and socket_tcp().

## ◆ socket_tcp6()

int socket_tcp6 | ( | void |  | ) |

Create a TCP/IPv6 socket.

## ◆ socket_udp()

int socket_udp | ( | void |  | ) |

Create a UDP/IP socket.

References socket_udp4().

Referenced by dns_transmit_free().

## ◆ socket_udp4()

int socket_udp4 | ( | void |  | ) |

Create a UDP/IPv4 socket.

Referenced by socket_udp().

## ◆ socket_udp6()

int socket_udp6 | ( | void |  | ) |

Create a UDP/IPv6 socket.

## ◆ socket_uncork()

int socket_uncork | ( | int | sock | ) |

Unstop a TCP socket from sending short writes.

## ◆ socket_unixdgm()

int socket_unixdgm | ( | void |  | ) |

Create UNIX domain datagram socket.

## ◆ socket_unixstr()

int socket_unixstr | ( | void |  | ) |

Create UNIX domain stream socket.