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_t 
The abstract type of socket type identifiers. The type parameter is a shadow type attributed to the socket type identifier value.
type 'a domain_t 
The abstract type of socket domain identifiers. The type parameter is a shadow type attributed to the protocol/address family identifier value.
type protocol_t 
The abstract type of socket protocol identifiers.
type 'a sockaddr_t 
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_t 
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_t = {
   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).

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.

Constants

val msg_flags_none : msg_flags_t
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 Berkely sockets API. For a more convenient interface, consider using the object-oriented alternative, described in the next section.

val create : 'a domain_t ->
'b socktype_t -> protocol_t -> ('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_t ->
'b socktype_t ->
protocol_t -> ('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_t -> 'a domain_t
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_t
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_t
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_t -> 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_t -> 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_t
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_t -> 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_t -> 'a sockaddr_t -> 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_t -> 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_t -> int * 'a sockaddr_t
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_t -> '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_t -> '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_t
Enables recording of debugging information.
val so_reuseaddr : (bool, 'a, 'b) sockopt_t
Enables local address reuse.
val so_reuseport : (bool, 'a, 'b) sockopt_t
Enables duplicate address and port bindings.
val so_keepalive : (bool, 'a, 'b) sockopt_t
Enables connection keep-alives.
val so_dontroute : (bool, 'a, 'b) sockopt_t
Enables routing bypass for outgoing messages.
val so_linger : (int option, 'a, 'b) sockopt_t
Enables linger on close if data present.
val so_broadcast : (bool, 'a, 'b) sockopt_t
Enables permission to transmit broadcast messages.
val so_oobinline : (bool, 'a, 'b) sockopt_t
Enables in-band reception of out-of-band/expedited messages.
val so_sndbuf : (int, 'a, 'b) sockopt_t
Set buffer size for output.
val so_rcvbuf : (int, 'a, 'b) sockopt_t
Set buffer size for input.
val so_sndlowat : (int, 'a, 'b) sockopt_t
Set minimum octet count for output.
val so_rcvlowat : (int, 'a, 'b) sockopt_t
Set minimum octet count for input.
val so_sndtimeo : (float, 'a, 'b) sockopt_t
Set timeout for output.
val so_rcvtimeo : (float, 'a, 'b) sockopt_t
Set timeout for input.
val so_error : (unit, 'a, 'b) sockopt_t
Get and clear the error on the socket (get only).
val so_nosigpipe : (bool, 'a, 'b) sockopt_t
Do not generate SIGPIPE. Instead raise Unix.Error Unix.EPIPE.