# Ocamlnet 4 Reference Manual

OCamlnet is an enhanced system platform library for Ocaml. As the name suggests, large parts of it have to do with network programming, but it is actually not restricted to this. Other parts deal with the management of multiple worker processes, and the interaction with other programs running on the same machine. You can also view Ocamlnet as an extension of the system interface as provided by the `Unix` module of the standard library.

Overview: What you can do with OCamlnet:

Domain | Task | Protocol/mechanism | Frameworks
Web applications | Dynamic web content, Connect with web server, Standalone web servers | Web server connectors: CGI, FastCGI, SCGI, AJP. HTTP server | Netcgi (connector framework)
Network applications (classic client/server) | SunRPC clients, SunRPC servers | SunRPC binary protocol, SunRPC stub generator, Portmapper/RPCBIND, RPCSEC_GSS | ``
Network applications (modern client/server) | Call HTTP interfaces, Provide HTTP interfaces | HTTP client, HTTP server, HTTP authentication | ``
Email applications | Create emails with attachments, Send emails, Parse emails, Interact with email server | SMTP client, POP client, SASL authentication | ``
Network utilities | Data download and upload, Encode and decode, Character sets, Structured formats, URLs, IPv6 | HTTP client, FTP client | Netfs (filesystem framework)
System utiltities | Invoke commands, Daemonize, Shared memory, Logging, Locales, Timers | `` | Netplex (multi-process daemons)
Authentication and security | Network authentication, Integrity protection, Privacy | TLS (via GnuTLS), SASL, GSSAPI (Kerberos) | Pluggable security providers for TLS, SASL, GSSAPI, Digests, Symmetric ciphers

## Introductory chapters

### Guides

- `Ocamlnet4`: Changes in OCamlnet-4
- `Foreword`: How Ocamlnet is organized
- `Platform`: Which functions are available on which platform (POSIX/Win32). Also hints for portable programming.
- `Ipv6`: The state of IPv6 support
- `Tls`: TLS support
- `Crypto`: Cryptography
- `Authentication`: Authentication frameworks
- `Credentials`: How to express and store credentials
- `Gssapi`: The GSSAPI security layer
- `Regexp`: Regular expression backends

## Contents by library

- Base Libraries
  - The netstring library: string processing functions
  - The netunidata library: Unicode tables
  - The netzip library: compression for object channels
  - The equeue library: concurrent execution flows via event queues
  - The netplex library: generic server framework
  - The netshm library: manage shared memory
  - The netsys library: system interfaces
- Web Programming
  - The netcgi2 library: web application framework
  - The netcgi2-apache library: run web apps inside Apache
  - The netcgi2-plex library: run web apps with Netplex
  - The nethttpd library: standalone web apps
- Client/Server Programming
  - The rpc library: SunRPC
  - The rpc-auth-local extension: authentication for local sockets
  - The rpc-xti extension: System V helpers
- Parallel Computing
  - The netcamlbox library: message passing
  - The netmulticore library: compute jobs
- Network Protocol Libraries
  - The netclient library: HTTP, FTP, Telnet, POP, SMTP

# Base Libraries

### Guides

- `Netchannels_tut`: The `Netchannels` tutorial - strongly recommended read!
- `Netmime_tut`: The `Netmime` tutorial
- `Netsendmail_tut`: The `Netsendmail` tutorial
- `Netulex_tut`: The `Netulex` tutorial
- `Neturl_tut`: The `Neturl` tutorial
- `Equeue_howto`: The Equeue, Unixqueue, and Engines HOWTO
- `Equeue_intro`: Introduction to programming with `equeue`
- `Netplex_intro`: Introduction to `Netplex`
- `Netplex_advanced`: Advanced features of `Netplex`
- `Netplex_admin`: Netplex administration guide
- `Netshm_intro`: Shared Memory for IPC
- `Shell_intro`: Motivation for `shell`

### External articles

## The `netstring` library: string processing functions

`netstring` focuses on string processing functions, and base definitions for other libraries.

Netaccel | Accelerators for bytecode
Netaccel_link | Enables accelerator module `Netaccel`
Netaddress | Parsing of mail addresses
Netasn1 | ASN.1 support functions
Netauth | Some primitives for authentication
Netaux | Internal auxiliary functions
Netbuffer | A Netbuffer.t is a buffer that can grow and shrink dynamically.
Netchannels | Object-oriented I/O: Basic types and classes
Netchannels_crypto | Crypto extensions for `Netchannels`
Netcompression | Registry for compression algorithms
Netconversion | Conversion between character encodings
Netdate | Support for common date/time parsing and formatting.
Netdn | X.500 distinguished names
Netencoding | Base64, Quoted Printable, URL encoding, HTML escaping
Netfs | Class type `stream_fs` for filesystems with stream access to files
Netglob | Globbing
Netgssapi_auth | Authentication helpers for GSSAPI
Netgssapi_support | Support functions for GSS-API
Nethtml | Parsing of HTML
Nethttp | Basic definitions for the HTTP protocol
Netmappings | Internal access to the character conversion database
Netmech_crammd5_sasl | The CRAM-MD5 SASL mechanism (RFC 2195), which is obsolete and only provided for completeness.
Netmech_digest_http | Digest authentication for HTTP
Netmech_digest_sasl | The DIGEST-MD5 SASL mechanism (RFC 2831).
Netmech_gs2_sasl | The GS2 bridge for using GSSAPI mechanisms as SASL mechanisms
Netmech_krb5_sasl | Kerberos 5 as SASL mechanism
Netmech_plain_sasl | The PLAIN SASL mechanism (RFC 4616).
Netmech_scram | SCRAM mechanism for authentication (RFC 5802)
Netmech_scram_gssapi | The SCRAM security mechanism for GSS-API
Netmech_scram_sasl | SCRAM as SASL mechanism
Netmech_spnego_http | SPNEGO (GSSAPI) authentication for HTTP
Netmime | Netmime contains high-level classes and functions to process mail and MIME messages.
Netmime_channels | MIME: parsing and printing for channels
Netmime_header | MIME: Access methods for frequent standard fields.
Netmime_string | Low-level functions to parse and print mail and MIME messages
Netnumber | Binary encodings of numbers
Netoid | X.500 Object Identifiers
Netpagebuffer | Buffer for page-aligned I/O
Netsaslprep | The SASLprep algorithm (RFC 4013)
Netsendmail | Functions to compose and send electronic mails
Netsockaddr | Parsing of socket addresses
Netstream | A netstream is an input channel that is read block by block.
Netstring_str | Wrapper for regexps with `Str` syntax
Nettls_support | Support types and functions for TLS
Netulex | Support module for Alain Frisch's `ulex` lexer generator
Netunichar | Unicode character information
Neturl | Uniform Resource Locators (URLs)
Netx509 | X.509 certificates
Netxdr | External Data Representation
Netxdr_mstring | Managed Strings

## The `netstring-pcre` library: additions for PCRE

Netstring_pcre | Wrapper for regexps with PCRE syntax

## The `netunidata` library: Unicode tables

Netunidata | Configure how to load Unicode tables

## The `netzip` library: compression for object channels

Support for (un)compressing data on the fly with object channels. Requires ocamlzip.

Netgzip | Gzip object channels

## The `equeue` library: concurrent execution flows via event queues

`equeue` is a fundamental library for event queues. It is mainly used by a number of other libraries of Ocamlnet to parallelize network code (so-called multiplexing).

Equeue | `Equeue` implements generic event queues.
Unixqueue | Unixqueues are one of the two forms of system event loops provided by Ocamlnet.
Unixqueue_pollset | Unixqueue implementation on top of `Netsys_pollset`
Unixqueue_select | This the old `Unix.select`-based imeplementation of event systems which was the default one until Ocamlnet-2.2.
Uq_engines | An engine performs a certain task in an autonomous way.
Uq_socks5 | This module implements a SOCKS version 5 client (see RFC 1928) for use with the `Uq_engines.connector`, `Uq_engines.listener`, and `Uq_engines.datagram_provider` engine factories.
Uq_resolver | Support for pluggable resolvers
Uq_io | Unified engines for stream I/O
Uq_client | Support for socket clients
Uq_server | Server sockets
Uq_multiplex | Multiplex Controllers
Uq_transfer | Transfer engines
Uq_lwt | Compatibility with `Lwt`
Uq_libevent | Use Libevent as event loop
Uq_mt | Using engines in multi-threaded programs

### The `equeue-gtk1` and `equeue-gtk2` extensions

Extensions for `equeue` to integrate the event queue into user interfaces made with lablgtk and lablgtk2

Uq_gtk | Integration with lablgtk/lablgtk2 event systems

### The `equeue-tcl` extension

Extension for `equeue` to integrate the event queue into user interfaces made with labltk

Uq_tcl | Integration with the labltk event system

## The `netplex` library: generic server framework

The `netplex` library is a protocol-independent server framework. Especially, it can be used in conjunction with `nethttpd` to build web servers, and with `rpc` to build RPC servers.

Netplex_types | Types for `Netplex`
Netplex_config | Read the configuration file
Netplex_controller | Controller
Netplex_container | Containers
Netplex_sockserv | Socket service creation
Netplex_workload | Workload management
Netplex_kit | Netplex toolkit
Netplex_cenv | Container environment
Netplex_log | Loggers
Netplex_main | Main program for Netplex servers
Netplex_mp | Multi-processing provider
Netplex_mt | Multi-threading provider
Netplex_mutex | Netplex-wide mutexes
Netplex_semaphore | Netplex-wide semaphores
Netplex_sharedvar | Netplex-wide variables
Netplex_mbox | Netplex message boxes
Netplex_encap | Type-safe marshalling between processes of the same executable
Rpc_netplex | Netplex support for RPC servers (TCP only)

## The `shell` library: start external commands

The `shell` library allows you to start external commands. It is integrated into `equeue`.

Shell | Calls external programs, creates pipelines, etc.
Shell_sys | Calls external programs, creates pipelines, etc.
Shell_uq | Run shell commands within Unixqueues
Shell_fs | Shell filesystem

## The `netshm` library: manage shared memory

The `netshm` library manages a shared memory object either as hash table or array. It is designed to be used in multi-processing program architectures. Note that there is now also the much better The netmulticore library: compute jobs library.

Netshm | Shared memory for O'Caml programs using multi-processing
Netshm_data | Data representation for shared memory
Netshm_hashtbl | Hash tables in shared memory
Netshm_array | Arrays in shared memory

## The `netsys` library: system interfaces

The `netsys` library contains a number of low-level functions used by other Ocamlnet libraries.

Platform |
Netexn | Exception registry
Netlog | Basic logging facility
Netsys | System calls missing in the `Unix` module
Netsys_posix | POSIX-specific system calls missing in the `Unix` module, and further API's from POSIX-style operating systems.
Netsys_oothr | Object-oriented thread API
Netsys_signal | Signal handler framework
Netsys_tmp | Temporary files
Netsys_mem | Bigarrays as memory buffers
Netsys_sem | Generic anonymous semaphores
Netsys_pollset | Sets of file descriptors for polling
Netsys_pollset_generic | Returns a good standard implementation of pollset for this platform.
Netsys_pollset_posix | Pollsets for POSIX operating systems
Netsys_pollset_win32 | Pollsets for Win32
Netsys_win32 | Primitives for Win32
Netsys_rng | Random-number generator
Netsys_crypto_types | Types for crypto providers
Netsys_crypto | Cryptographic providers
Netsys_crypto_modes | Helpers for crypto modes
Netsys_tls | User-level TLS API
Netsys_ciphers | Symmetric cryptographic ciphers
Netsys_digests | Cryptographic digests (hashes)
Netsys_gssapi | GSS-API Definition

## The `nettls-gnutls` library: GnuTLS bindings

Nettls_gnutls | GnuTLS
Nettls_gnutls_bindings | Bindings of a C library
Nettls_nettle_bindings | Bindings of a C library

## The `netgss` library: GSSAPI bindings

Netgss | This is the system-wide version of GSSAPI
Netgss_bindings | Bindings of a C library

# Web Programming

### Guides

- `Netcgi_porting`: Porting `netcgi1` programs to `netcgi2`
- `Nethttpd_intro`: Overview over the HTTP daemon

### The `netcgi1` library

The `netcgi1` library is no longer supported in Ocamlnet 3. Please switch to `netcgi2`.

## The `netcgi2` library: web application framework

This is the revised library for Web applications, now called `netcgi2`.

Netcgi | Common data-structures for CGI-like connectors.
Netcgi_common | Functions to develop new connectors.
Netcgi_cgi | Classical CGI connector.
Netcgi_fcgi | FastCGI connector.
Netcgi_ajp | Apache JServ Protocol (AJP) 1.3 connector.
Netcgi_scgi | SCGI connector.
Netcgi_test | Connector for testing your code.
Netcgi_dbi | Pools of connections for the ocamldbi generic database interface.
Netcgi1_compat | Compatibility module with the previous version of Netcgi.

## The `netcgi2-apache` library: run web apps inside Apache

This is an Apache connector for the `netcgi2` library.

Netcgi_apache | Netcgi Apache "mod" connector.
Netcgi_modtpl |

## The `netcgi2-plex` library: run web apps with Netplex

Netplex support for running Netcgi2 connectors:

Netcgi_plex | Netplex support for FastCGI, SCGI and AJP connectors

## The `nethttpd` library: standalone web apps

The `nethttpd` library is a Web server component written in O'Caml. For a full web server, you'll also need `netplex`.

Nethttpd_types | Type definitions for the HTTP daemon
Nethttpd_kernel | The protocol kernel of the HTTP daemon
Nethttpd_reactor | The reactive encapsulation of the HTTP daemon
Nethttpd_engine | The event-based encapsulation of the HTTP daemon
Nethttpd_services | Service Providers for HTTP daemon
Nethttpd_plex | Netplex support
Nethttpd_util | Utility functions

# Client/Server Programming

### Guides

- `Rpc_intro`: Introduction
- `Rpc_mapping_ref`: RPC Language Mapping Reference
- `Rpc_intro_gss`: Securing RPC with the GSS-API

### External articles

## The `rpc` library: SunRPC

This library implements OncRPC (alias SunRPC).

Rpc | Common types and exceptions
Rpc_program | RPC programs
Rpc_client | RPC clients
Rpc_simple_client | Synchronous API for RPC clients
Rpc_proxy | RPC proxies
Rpc_server | RPC servers
Rpc_auth_sys | Authentication module AUTH_SYS
Rpc_portmapper | Portmapper/RPCBIND interface
Rpc_portmapper_aux |
Rpc_portmapper_clnt |
Rpc_transport | Low-level RPC transporters
Rpc_packer | The first n bytes of the packed value
Rpc_auth_gssapi | GSS-API for RPC authentication

## The `rpc-auth-local` extension: authentication for local sockets

Authentication for local socket connections.

Rpc_auth_local | Return the authentication method `AUTH_LOCAL`.

## The `rpc-xti` extension: System V helpers

System V provides a network API called XTI in addition to the socket API. This library allows it to connect to RPC services that can only be reached over a local XTI connection ("cots" connection).

Rpc_xti_client | Minimal support for TI-RPC over the XTI API

# Parallel Computing

### Guides

- `Netmcore_basics`: Basics
- `Netmcore_tut`: Tutorial

Important change since OCaml-4.01: This OCaml version changed the semantics of the built-in primitives `caml_modify` and `caml_initialize`. Essentially, it is no longer possible to modify OCaml values residing outside the regular OCaml heap. As we do this inside Netcamlbox and Netmulticore, this change affects these libraries. Fortunately, there is a workaround on systems supporting weak symbols (all ELF systems and OS X): Here, `caml_modify` and `caml_initialize` are overridden by Ocamlnet so that they are again compatible. Note that this is a global modification of the runtime system!

## The `netcamlbox` library: message passing

Camlbox is a fast message-passing system between processes running on the same machine. It uses shared memory for communication. A message sent to a Camlbox is only copied once, not twice.

Netcamlbox | Camlboxes are a fast IPC mechanism to send Ocaml values from one process to another.

## The `netmulticore` library: compute jobs

Netmulticore is an experimental framework for managing multiple processes, and sending messages between them.

Netmcore | Multi-processing for compute jobs
Netmcore_process | Statically typed processes
Netmcore_mempool | Memory pools
Netmcore_heap | Shared heaps of structured values
Netmcore_array | Shared arrays
Netmcore_buffer | Shared buffer
Netmcore_hashtbl | Shared hashtables
Netmcore_matrix | Shared 2-dimensional arrays (matrices)
Netmcore_queue | Shared queues
Netmcore_ref | Shared mutable variables
Netmcore_mutex | Mutexes
Netmcore_sem | Semaphores
Netmcore_condition | Condition variables
Netmcore_camlbox | Camlboxes for use in netmulticore programs

# Network Protocol Libraries

### Guides

- `Netclient_tut`: The Netclient tutorial (HTTP, FTP)

## The `netclient` library: HTTP, FTP, Telnet, POP, SMTP

This library includes clients for HTTP, Telnet, FTP, SMTP, and POP.

Nethttp_client | HTTP 1.1 client
Nethttp_client_conncache | Connection cache
Nethttp_fs | HTTP filesystem
Netftp_client | FTP client
Netftp_data_endpoint | Senders and receivers for the FTP data connection
Netftp_fs | FTP filesystem
Nettelnet_client | Telnet client
Netpop | This is an interface for the Post Office Protocol - Version 3 (POP3) as specifed by RFC 1939.
Netsmtp | This is an interface for the Simple Mail Tranfer Protocol (SMTP) as specified by RFC 2821.

# Trailer

## Index

- Index of types
- Index of exceptions
- Index of values
- Index of class attributes
- Index of class methods
- Index of classes
- Index of class types
- Index of modules
- Index of module types

## Authors

The Ocamlnet libraries have been initially written by Gerd Stolpmann and Patrick Doane.

Contributions by

- Nicolas George: Netdate
- Eric Stokes: FastCGI support
- Pierre Habouzit: SMTP client
- Christophe Troestler: Revised version of `netcgi`
- Deokhwan Kim: Support for EUC-KR

Sponsorships by

- Baretta s.r.l: Nethttpd
- California State University: SSL support for RPC, Netplex