Module Cf_socket

module Cf_socket: sig .. end

Extended network sockets interface.

Overview

The Objective Caml Unix library contains a simplified interface for manipulating network sockets that is sufficient for most applications. This module and its cognates implement an alternative interface for using network sockets that offers the same extensibility as the Berkeley sockets interface does in the C language, while using the Objective Caml type system to enforce usage constraints.

Types

type 'a socktype

The abstract type of socket type identifiers. The type parameter is a shadow type attributed to the socket type identifier value.

type 'a domain

The abstract type of socket domain identifiers. The type parameter is a shadow type attributed to the protocol/address family identifier value.

type protocol

The abstract type of socket protocol identifiers.

type 'a sockaddr

The abstract type of socket address structures. Internally, these are represented as custom Objective Caml blocks of precisely the size of the underlying struct sockaddr_xxx structure. The type parameter is a shadow type attributed to the address family identifier value.

type ('a, -'b, -'c) sockopt

The abstract type of socket option identifiers. The first type parameter is the type of values the socket option sets and gets. The second type parameter is the shadow type used to constrain the use of the option to sockets of the appropriate protocol family. The third type parameter is the shadow type used to constrain the use of the option to sockets of the appropriate socket type.

type ('a, 'b) t

The abstract type of socket descriptors. The type parameters are the shadow types associated with the protocol/address family and the socket type of the socket, respectively.

type msg_flags = {

`msg_oob : bool;`	`(*`	Message is out-of-band/expedited.	`*)`
`msg_peek : bool;`	`(*`	Read message without dequeue.	`*)`
`msg_dontroute : bool;`	`(*`	Use direct interface.	`*)`
`msg_eor : bool;`	`(*`	End of record.	`*)`
`msg_trunc : bool;`	`(*`	Message truncated in receive.	`*)`
`msg_ctrunc : bool;`	`(*`	Control message truncated in receive.	`*)`
`msg_waitall : bool;`	`(*`	Block until message completely received.	`*)`
`msg_dontwait : bool;`	`(*`	Don't block.	`*)`

}

The record used to select the flags used with the send and recv functions (and their cognates).

Modules and Module Types

module type AF = sig .. end

The module type used to define a socket address/protocol family.

module type ST = sig .. end

The module type used to define a socket type.

module type P = sig .. end

The module type used to define a socket protocol.

module SOCK_STREAM: ST  with type tag = [ `SOCK_STREAM ]

The module defining the SOCK_STREAM socket type.

module SOCK_DGRAM: ST  with type tag = [ `SOCK_DGRAM ]

Constants

val msg_flags_none : msg_flags

The default value of the message flags structure, i.e. no flags set.

Functions

Most of the functions here are fairly straightforward wrappers around the Berkeley sockets API. For a more convenient interface, consider using the object-oriented alternative, described in the next section.

val create : 'a domain ->
       'b socktype -> protocol -> ('a, 'b) t

Use create dom st p to create a new socket descriptor with the socket domain dom, the socket type st and the protocol identifier p. Raises Unix.Error if a system error occurs.

val createpair : 'a domain ->
       'b socktype ->
       protocol -> ('a, 'b) t * ('a, 'b) t

Use createpair dom st p to create a pair of new socket descriptors that are already bound and connected to one another, using the socket domain dom, the socket type st and the protocol identifier p. Raises Unix.Error if a system error occurs.

val to_unix_file_descr : ('a, 'b) t -> Unix.file_descr

Use to_unix_file_descr sock to obtain the file descriptor to use with functions in the Unix library that corresponds to the socket descriptor sock.

val domain_of_sockaddr : 'a sockaddr -> 'a domain

Use domain_of_sockaddr sa to obtain the socket domain identifier associated with a socket address of unknown address family.

val dup : ('a, 'b) t -> ('a, 'b) t

Use dup sock to create a duplicate of socket descriptor sock. Raises Unix.Error if there is an error.

val dup2 : ('a, 'b) t -> ('a, 'b) t -> unit

Use dup2 sock sock2 to create a duplicate of socket descriptor sock by overwriting the descriptor sock2. Raises Unix.Error if there is an error.

val getsockname : ('a, 'b) t -> 'a sockaddr

Use getsockname sock to create a new socket address corresponding to the local bound endpoint of the socket sock. Raises Unix.Error if there is an error.

val getpeername : ('a, 'b) t -> 'a sockaddr

Use getpeername sock to create a new socket address corresponding to the connected remote endpoint of the socket sock. Raises Unix.Error if there is an error.

val bind : ('a, 'b) t -> 'a sockaddr -> unit

Use bind sock sa to bind the local endpoint address of the socket sock to the socket address sa. Raises Unix.Error if there is an error.

val connect : ('a, 'b) t -> 'a sockaddr -> unit

Use connect sock sa to connect the remote endpoint address of the socket sock to the socket address sa. Raises Unix.Error if there is an error.

val listen : ('a, [< `SOCK_SEQPACKET | `SOCK_STREAM ]) t -> int -> unit

Use listen sock n to set the socket sock into the mode of listening for connections with a backlog queue n spaces deep. Raises Unix.Error if there is an error.

val accept : ('a, [ `SOCK_STREAM ]) t ->
       ('a, [ `SOCK_STREAM ]) t * 'a sockaddr

Use accept sock to accept a connected request on the listening socket sock. Returns a new socket descriptor and the socket address of the remote peer. Raises Unix.Error if there is an error.

val shutdown : ('a, 'b) t -> Unix.shutdown_command -> unit

Use shutdown sock cmd to shutdown either sending or receiving (or both) on the socket sock. Raises Unix.Error if there is an error.

val close : ('a, 'b) t -> unit

Use close sock to close a socket descriptor. Raises Unix.Error if there is an error.

val send : ('a, 'b) t -> string -> int -> int -> msg_flags -> int

Use send sock buf pos len flags to send len octets from the string buf starting at position pos on the socket sock with the flags indicated by flags. Returns the number of octets actually sent. Raises Unix.Error if there is an error. Raises Invalid_argument if pos and len do not correspond to a valid substring of buf.

val sendto : ('a, [ `SOCK_DGRAM ]) t ->
       string -> int -> int -> msg_flags -> 'a sockaddr -> int

Use sendto sock buf pos len flags sa to send len octets from the string buf starting at position pos on the socket sock with the flags indicated by flags to the socket address sa. Returns the number of octets actually sent. Raises Unix.Error if there is an error. Raises Invalid_argument if pos and len do not correspond to a valid substring of buf.

val recv : ('a, 'b) t -> string -> int -> int -> msg_flags -> int

Use recv sock buf pos len flags to receive len octets into the string buf starting at position pos on the socket sock with the flags indicated by flags. Returns the number of octets actually received. Raises Unix.Error if there is an error. Raises Invalid_argument if pos and len do not correspond to a valid substring of buf.

val recvfrom : ('a, [ `SOCK_DGRAM ]) t ->
       string -> int -> int -> msg_flags -> int * 'a sockaddr

Use recvfrom sock buf pos len flags to receive len octets into the string buf starting at position pos on the socket sock with the flags indicated by flags. Returns the number of octets actually received and the socket address of the remote endpoint that sent them. Raises Unix.Error if there is an error. Raises Invalid_argument if pos and len do not correspond to a valid substring of buf.

val getsockopt : ('a, 'b) t -> ('c, 'a, 'b) sockopt -> 'c

Use getsockopt sock opt to obtain the value associated with the socket option opt for the socket descriptor sock. Raises Unix.Error if there is an error.

val setsockopt : ('a, 'b) t -> ('c, 'a, 'b) sockopt -> 'c -> unit

Use setsockopt sock opt v to set the value associated with the socket option opt for the socket descriptor sock to the value v. Raises Unix.Error if there is an error.

Socket Options

The following socket options are available on sockets of all socket types and address/protocol families.

val so_debug : (bool, 'a, 'b) sockopt

Enables recording of debugging information.

val so_reuseaddr : (bool, 'a, 'b) sockopt

Enables local address reuse.

val so_reuseport : (bool, 'a, 'b) sockopt

Enables duplicate address and port bindings.

val so_keepalive : (bool, 'a, 'b) sockopt

Enables connection keep-alives.

val so_dontroute : (bool, 'a, 'b) sockopt

Enables routing bypass for outgoing messages.

val so_linger : (int option, 'a, 'b) sockopt

Enables linger on close if data present.

val so_broadcast : (bool, 'a, 'b) sockopt

Enables permission to transmit broadcast messages.

val so_oobinline : (bool, 'a, 'b) sockopt

Enables in-band reception of out-of-band/expedited messages.

val so_sndbuf : (int, 'a, 'b) sockopt

Set buffer size for output.

val so_rcvbuf : (int, 'a, 'b) sockopt

Set buffer size for input.

val so_sndlowat : (int, 'a, 'b) sockopt

Set minimum octet count for output.

val so_rcvlowat : (int, 'a, 'b) sockopt

Set minimum octet count for input.

val so_sndtimeo : (float, 'a, 'b) sockopt

Set timeout for output.

val so_rcvtimeo : (float, 'a, 'b) sockopt

Set timeout for input.

val so_error : (unit, 'a, 'b) sockopt

Get and clear the error on the socket (get only).

val so_nosigpipe : (bool, 'a, 'b) sockopt

Do not generate SIGPIPE. Instead raise Unix.Error Unix.EPIPE.