package posix-socket

  1. Overview
  2. Docs

Module Posix_socketSource

POSIX socket interface bindings.

This module provides OCaml bindings to the POSIX socket API defined in sys/socket.h and netdb.h.

It includes functions for address resolution, byte order conversion, and socket address manipulation.

Error Handling

Error codes returned by address resolution functions like getaddrinfo and getnameinfo.

Sourcetype error = [
  1. | `ADDRFAMILY
    (*

    Address family not supported

    *)
  2. | `AGAIN
    (*

    Temporary failure in name resolution

    *)
  3. | `BADFLAGS
    (*

    Invalid flags value

    *)
  4. | `BADHINTS
    (*

    Invalid hints value

    *)
  5. | `FAIL
    (*

    Non-recoverable failure in name resolution

    *)
  6. | `FAMILY
    (*

    Address family not supported

    *)
  7. | `MEMORY
    (*

    Memory allocation failure

    *)
  8. | `NODATA
    (*

    No address associated with hostname

    *)
  9. | `NONAME
    (*

    Name or service not known

    *)
  10. | `PROTOCOL
    (*

    Resolved protocol is unknown

    *)
  11. | `SOCKTYPE
    (*

    Socket type not supported

    *)
  12. | `OVERFLOW
    (*

    Argument buffer overflow

    *)
  13. | `SERVICE
    (*

    Service not supported for socket type

    *)
  14. | `SYSTEM
    (*

    System error, check errno

    *)
  15. | `UNKNOWN of int
    (*

    Unknown error code

    *)
]

Address resolution error codes (EAI_* constants).

Sourceval int_of_error : error -> int

Convert an error to its integer representation.

Sourceval error_of_int : int -> error

Convert an integer to an error code.

Sourceval is_native : error -> bool

Returns true if this error code is natively defined on this platform.

Sourceval strerror : error -> string

Return a human-readable error message. See gai_strerror(3).

Sourceexception Error of error

Exception raised by address resolution functions on error.

Byte Order Conversion

Functions for converting between network byte order (big-endian) and host byte order. See byteorder(3).

Sourceval ntohl : Unsigned.uint32 -> Unsigned.uint32

Convert 32-bit integer from network to host byte order.

Sourceval ntohs : Unsigned.uint16 -> Unsigned.uint16

Convert 16-bit integer from network to host byte order.

Sourceval htonl : Unsigned.uint32 -> Unsigned.uint32

Convert 32-bit integer from host to network byte order.

Sourceval htons : Unsigned.uint16 -> Unsigned.uint16

Convert 16-bit integer from host to network byte order.

Socket Types

Socket type constants used when creating sockets. See socket(2).

Sourcetype socket_type

Abstract type representing socket types.

Sourceval socket_type_t : socket_type Ctypes.typ

Ctypes representation of socket_type.

Sourceval sock_dgram : socket_type

Datagram socket (connectionless, unreliable). Used with UDP.

Sourceval sock_stream : socket_type

Stream socket (connection-oriented, reliable). Used with TCP.

Sourceval sock_seqpacket : socket_type

Sequenced packet socket (connection-oriented, reliable, message boundaries preserved).

Address Families

Socket address family constants. See sys/socket.h.

Module for the sa_family field type.

Sourcetype sa_family_t = Sa_family.t

Type alias for address family.

Sourceval sa_family_t : sa_family_t Ctypes.typ

Ctypes representation of sa_family_t.

Sourceval af_inet : sa_family_t

IPv4 address family (AF_INET).

Sourceval af_inet6 : sa_family_t

IPv6 address family (AF_INET6).

Sourceval af_unspec : sa_family_t

Unspecified address family (AF_UNSPEC). Used to request any address family.

Name Resolution Constants

Constants for getnameinfo(3).

Sourceval ni_maxserv : int

Maximum length of a service name string.

Sourceval ni_maxhost : int

Maximum length of a host name string.

Sourceval ni_numerichost : int

Return numeric form of the host address.

Sourceval ni_numericserv : int

Return numeric form of the service (port number).

Protocol Constants

IP protocol numbers for use with sockets. See netinet/in.h.

Sourceval ipproto_ip : int

Internet Protocol (IP).

Sourceval ipproto_ipv6 : int

Internet Protocol version 6 (IPv6).

Sourceval ipproto_icmp : int

Internet Control Message Protocol (ICMP).

Sourceval ipproto_raw : int

Raw IP packets.

Sourceval ipproto_tcp : int

Transmission Control Protocol (TCP).

Sourceval ipproto_udp : int

User Datagram Protocol (UDP).

Socket Length Type

The socklen_t type used for socket address lengths. See sys/socket.h.

Sourcemodule Socklen : Unsigned.S

Unsigned module for socklen_t arithmetic.

Sourcetype socklen_t

Abstract socklen_t type.

Sourceval socklen_t : socklen_t Ctypes.typ

Ctypes representation of socklen_t.

Socket Address Storage

Generic socket address storage large enough to hold any socket address type. See sockaddr_storage.

Sourcetype sockaddr_storage

Abstract type for socket address storage.

Sourceval sockaddr_storage : unit -> sockaddr_storage Ctypes.ptr

Allocate a new socket address storage structure.

Sourceval sockaddr_storage_len : int

Size of sockaddr_storage in bytes.

Generic Socket Address

The generic sockaddr structure. See sockaddr.

Sourcemodule Sockaddr : sig ... end

Generic socket address structure.

Type alias for sockaddr structure.

Sourceval sockaddr_t : sockaddr Ctypes.typ

Ctypes representation of sockaddr.

Sourceval sockaddr_len : sockaddr Ctypes.ptr -> int

Return the actual length of a socket address based on its family.

Address Info

The addrinfo structure used by getaddrinfo. See getaddrinfo(3).

Sourcemodule Addrinfo : sig ... end

Address information structure returned by getaddrinfo.

Port Type

Sourcetype in_port = Unsigned.uint16

Port number type (16-bit unsigned integer in network byte order).

Sourceval in_port_t : Unsigned.uint16 Ctypes.typ

Ctypes representation of in_port_t.

IPv4 Socket Address

The sockaddr_in structure for IPv4 addresses. See netinet/in.h.

Sourcemodule SockaddrInet : sig ... end

IPv4 socket address structure.

Type alias for IPv4 socket address.

Sourceval sockaddr_in_t : sockaddr_in Ctypes.typ

Ctypes representation of sockaddr_in.

IPv6 Socket Address

The sockaddr_in6 structure for IPv6 addresses. See netinet/in.h.

Sourcemodule SockaddrInet6 : sig ... end

IPv6 socket address structure.

Type alias for IPv6 socket address.

Sourceval sockaddr_in6_t : sockaddr_in6 Ctypes.typ

Ctypes representation of sockaddr_in6.

Address Resolution Functions

Sourceval getnameinfo : sockaddr Ctypes.ptr -> string * int

Convert a socket address to a hostname and port number.

This is a wrapper around getnameinfo(3).

  • parameter sockaddr

    The socket address to convert.

  • returns

    A tuple (hostname, port).

  • raises Error

    if the conversion fails.

Sourceval getaddrinfo : ?hints:Addrinfo.t Ctypes.structure Ctypes.ptr -> ?port:[ `Int of int | `String of string ] -> string -> sockaddr Ctypes.ptr list

Resolve a hostname to a list of socket addresses.

This is a wrapper around getaddrinfo(3).

  • parameter hints

    Optional hints to filter results.

  • parameter port

    Optional port number or service name.

  • parameter hostname

    The hostname to resolve.

  • returns

    A list of socket addresses.

  • raises Error

    if resolution fails.

Example:

  let addresses = getaddrinfo ~port:(`Int 443) "example.com" in
  List.iter
    (fun addr ->
      let host, port = getnameinfo addr in
      Printf.printf "%s:%d\n" host port)
    addresses

Utility Functions

Sourceval strnlen : char Ctypes.ptr -> Unsigned.size_t -> Unsigned.size_t

Calculate the length of a null-terminated string up to a maximum. See strnlen(3).

Unix Module Interoperability

Functions for converting between Unix.sockaddr and POSIX socket addresses.

Sourceval from_unix_sockaddr : Unix.sockaddr -> sockaddr Ctypes.ptr

Convert a Unix.sockaddr to a POSIX socket address.

  • parameter addr

    The Unix socket address to convert.

  • returns

    A pointer to the equivalent POSIX sockaddr.

Sourceval to_unix_sockaddr : sockaddr Ctypes.ptr -> Unix.sockaddr

Convert a POSIX socket address to Unix.sockaddr.

  • parameter addr

    The POSIX socket address to convert.

  • returns

    The equivalent Unix socket address.