diff --git a/iostream/Iostream_unix/In/index.html b/iostream/Iostream_unix/In/index.html index 68397599..34e85eb8 100644 --- a/iostream/Iostream_unix/In/index.html +++ b/iostream/Iostream_unix/In/index.html @@ -1,2 +1,2 @@ -In (iostream.Iostream_unix.In)

Module Iostream_unix.In

val of_unix_fd : ?close_noerr:bool -> Unix.file_descr -> Iostream.In.t_seekable

Create an in stream from a raw Unix file descriptor. The file descriptor must be opened for reading.

+In (iostream.Iostream_unix.In)

Module Iostream_unix.In

val of_unix_fd : ?close_noerr:bool -> Unix.file_descr -> Iostream.In.t_seekable

Create an in stream from a raw Unix file descriptor. The file descriptor must be opened for reading.

diff --git a/iostream/Iostream_unix/Out/index.html b/iostream/Iostream_unix/Out/index.html index 64545ea8..e16cce11 100644 --- a/iostream/Iostream_unix/Out/index.html +++ b/iostream/Iostream_unix/Out/index.html @@ -1,2 +1,2 @@ -Out (iostream.Iostream_unix.Out)

Module Iostream_unix.Out

Output stream directly writing into the given Unix file descriptor.

+Out (iostream.Iostream_unix.Out)

Module Iostream_unix.Out

val of_unix_fd : Unix.file_descr -> Iostream.Out.t_seekable

Output stream directly writing into the given Unix file descriptor.

diff --git a/ocaml/Unix/index.html b/ocaml/Unix/index.html index 6a208bdb..9188727b 100644 --- a/ocaml/Unix/index.html +++ b/ocaml/Unix/index.html @@ -17,7 +17,7 @@ Stdlib.Bigarray.Array1.t -> int -> int -> - int

Same as single_write, but take the data from a bigarray.

Interfacing with the standard input/output library

val in_channel_of_descr : file_descr -> in_channel

Create an input channel reading from the given descriptor. The channel is initially in binary mode; use set_binary_mode_in ic false if text mode is desired. Text mode is supported only if the descriptor refers to a file or pipe, but is not supported if it refers to a socket.

On Windows: Stdlib.set_binary_mode_in always fails on channels created with this function.

Beware that input channels are buffered, so more characters may have been read from the descriptor than those accessed using channel functions. Channels also keep a copy of the current position in the file.

Closing the channel ic returned by in_channel_of_descr fd using close_in ic also closes the underlying descriptor fd. It is incorrect to close both the channel ic and the descriptor fd.

If several channels are created on the same descriptor, one of the channels must be closed, but not the others. Consider for example a descriptor s connected to a socket and two channels ic = in_channel_of_descr s and oc = out_channel_of_descr s. The recommended closing protocol is to perform close_out oc, which flushes buffered output to the socket then closes the socket. The ic channel must not be closed and will be collected by the GC eventually.

val out_channel_of_descr : file_descr -> out_channel

Create an output channel writing on the given descriptor. The channel is initially in binary mode; use set_binary_mode_out oc false if text mode is desired. Text mode is supported only if the descriptor refers to a file or pipe, but is not supported if it refers to a socket.

On Windows: Stdlib.set_binary_mode_out always fails on channels created with this function.

Beware that output channels are buffered, so you may have to call Stdlib.flush to ensure that all data has been sent to the descriptor. Channels also keep a copy of the current position in the file.

Closing the channel oc returned by out_channel_of_descr fd using close_out oc also closes the underlying descriptor fd. It is incorrect to close both the channel ic and the descriptor fd.

See Unix.in_channel_of_descr for a discussion of the closing protocol when several channels are created on the same descriptor.

val descr_of_in_channel : in_channel -> file_descr

Return the descriptor corresponding to an input channel.

val descr_of_out_channel : out_channel -> file_descr

Return the descriptor corresponding to an output channel.

Seeking and truncating

type seek_command =
  1. | SEEK_SET
    (*

    indicates positions relative to the beginning of the file

    *)
  2. | SEEK_CUR
    (*

    indicates positions relative to the current position

    *)
  3. | SEEK_END
    (*

    indicates positions relative to the end of the file

    *)

Positioning modes for lseek.

val lseek : file_descr -> int -> seek_command -> int

Set the current position for a file descriptor, and return the resulting offset (from the beginning of the file).

val truncate : string -> int -> unit

Truncates the named file to the given size.

val ftruncate : file_descr -> int -> unit

Truncates the file corresponding to the given descriptor to the given size.

File status

type file_kind =
  1. | S_REG
    (*

    Regular file

    *)
  2. | S_DIR
    (*

    Directory

    *)
  3. | S_CHR
    (*

    Character device

    *)
  4. | S_BLK
    (*

    Block device

    *)
  5. | S_LNK
    (*

    Symbolic link

    *)
  6. | S_FIFO
    (*

    Named pipe

    *)
  7. | S_SOCK
    (*

    Socket

    *)
type stats = {
  1. st_dev : int;
    (*

    Device number

    *)
  2. st_ino : int;
    (*

    Inode number

    *)
  3. st_kind : file_kind;
    (*

    Kind of the file

    *)
  4. st_perm : file_perm;
    (*

    Access rights

    *)
  5. st_uid : int;
    (*

    User id of the owner

    *)
  6. st_gid : int;
    (*

    Group ID of the file's group

    *)
  7. st_rdev : int;
    (*

    Device ID (if special file)

    *)
  8. st_size : int;
    (*

    Size in bytes

    *)
  9. st_atime : float;
    (*

    Last access time

    *)
  10. st_mtime : float;
    (*

    Last modification time

    *)
  11. st_ctime : float;
    (*

    Last status change time

    *)
}

The information returned by the stat calls.

val stat : string -> stats

Return the information for the named file.

val lstat : string -> stats

Same as stat, but in case the file is a symbolic link, return the information for the link itself.

val fstat : file_descr -> stats

Return the information for the file associated with the given descriptor.

val isatty : file_descr -> bool

Return true if the given file descriptor refers to a terminal or console window, false otherwise.

File operations on large files

module LargeFile : sig ... end

File operations on large files. This sub-module provides 64-bit variants of the functions lseek (for positioning a file descriptor), truncate and ftruncate (for changing the size of a file), and stat, lstat and fstat (for obtaining information on files). These alternate functions represent positions and sizes by 64-bit integers (type int64) instead of regular integers (type int), thus allowing operating on files whose sizes are greater than max_int.

Mapping files into memory

val map_file : + int

Same as single_write, but take the data from a bigarray.

Interfacing with the standard input/output library

val in_channel_of_descr : file_descr -> Stdlib.in_channel

Create an input channel reading from the given descriptor. The channel is initially in binary mode; use set_binary_mode_in ic false if text mode is desired. Text mode is supported only if the descriptor refers to a file or pipe, but is not supported if it refers to a socket.

On Windows: Stdlib.set_binary_mode_in always fails on channels created with this function.

Beware that input channels are buffered, so more characters may have been read from the descriptor than those accessed using channel functions. Channels also keep a copy of the current position in the file.

Closing the channel ic returned by in_channel_of_descr fd using close_in ic also closes the underlying descriptor fd. It is incorrect to close both the channel ic and the descriptor fd.

If several channels are created on the same descriptor, one of the channels must be closed, but not the others. Consider for example a descriptor s connected to a socket and two channels ic = in_channel_of_descr s and oc = out_channel_of_descr s. The recommended closing protocol is to perform close_out oc, which flushes buffered output to the socket then closes the socket. The ic channel must not be closed and will be collected by the GC eventually.

val out_channel_of_descr : file_descr -> Stdlib.out_channel

Create an output channel writing on the given descriptor. The channel is initially in binary mode; use set_binary_mode_out oc false if text mode is desired. Text mode is supported only if the descriptor refers to a file or pipe, but is not supported if it refers to a socket.

On Windows: Stdlib.set_binary_mode_out always fails on channels created with this function.

Beware that output channels are buffered, so you may have to call Stdlib.flush to ensure that all data has been sent to the descriptor. Channels also keep a copy of the current position in the file.

Closing the channel oc returned by out_channel_of_descr fd using close_out oc also closes the underlying descriptor fd. It is incorrect to close both the channel ic and the descriptor fd.

See Unix.in_channel_of_descr for a discussion of the closing protocol when several channels are created on the same descriptor.

val descr_of_in_channel : Stdlib.in_channel -> file_descr

Return the descriptor corresponding to an input channel.

val descr_of_out_channel : Stdlib.out_channel -> file_descr

Return the descriptor corresponding to an output channel.

Seeking and truncating

type seek_command =
  1. | SEEK_SET
    (*

    indicates positions relative to the beginning of the file

    *)
  2. | SEEK_CUR
    (*

    indicates positions relative to the current position

    *)
  3. | SEEK_END
    (*

    indicates positions relative to the end of the file

    *)

Positioning modes for lseek.

val lseek : file_descr -> int -> seek_command -> int

Set the current position for a file descriptor, and return the resulting offset (from the beginning of the file).

val truncate : string -> int -> unit

Truncates the named file to the given size.

val ftruncate : file_descr -> int -> unit

Truncates the file corresponding to the given descriptor to the given size.

File status

type file_kind =
  1. | S_REG
    (*

    Regular file

    *)
  2. | S_DIR
    (*

    Directory

    *)
  3. | S_CHR
    (*

    Character device

    *)
  4. | S_BLK
    (*

    Block device

    *)
  5. | S_LNK
    (*

    Symbolic link

    *)
  6. | S_FIFO
    (*

    Named pipe

    *)
  7. | S_SOCK
    (*

    Socket

    *)
type stats = {
  1. st_dev : int;
    (*

    Device number

    *)
  2. st_ino : int;
    (*

    Inode number

    *)
  3. st_kind : file_kind;
    (*

    Kind of the file

    *)
  4. st_perm : file_perm;
    (*

    Access rights

    *)
  5. st_uid : int;
    (*

    User id of the owner

    *)
  6. st_gid : int;
    (*

    Group ID of the file's group

    *)
  7. st_rdev : int;
    (*

    Device ID (if special file)

    *)
  8. st_size : int;
    (*

    Size in bytes

    *)
  9. st_atime : float;
    (*

    Last access time

    *)
  10. st_mtime : float;
    (*

    Last modification time

    *)
  11. st_ctime : float;
    (*

    Last status change time

    *)
}

The information returned by the stat calls.

val stat : string -> stats

Return the information for the named file.

val lstat : string -> stats

Same as stat, but in case the file is a symbolic link, return the information for the link itself.

val fstat : file_descr -> stats

Return the information for the file associated with the given descriptor.

val isatty : file_descr -> bool

Return true if the given file descriptor refers to a terminal or console window, false otherwise.

File operations on large files

module LargeFile : sig ... end

File operations on large files. This sub-module provides 64-bit variants of the functions lseek (for positioning a file descriptor), truncate and ftruncate (for changing the size of a file), and stat, lstat and fstat (for obtaining information on files). These alternate functions represent positions and sizes by 64-bit integers (type int64) instead of regular integers (type int), thus allowing operating on files whose sizes are greater than max_int.

Mapping files into memory

val map_file : file_descr -> ?pos:int64 -> ('a, 'b) Stdlib.Bigarray.kind -> @@ -37,15 +37,20 @@ file_descr -> file_descr -> file_descr -> - int

create_process_env prog args env stdin stdout stderr works as create_process, except that the extra argument env specifies the environment passed to the program.

val open_process_in : string -> in_channel

High-level pipe and process management. This function runs the given command in parallel with the program. The standard output of the command is redirected to a pipe, which can be read via the returned input channel. The command is interpreted by the shell /bin/sh (or cmd.exe on Windows), cf. system. The Filename.quote_command function can be used to quote the command and its arguments as appropriate for the shell being used. If the command does not need to be run through the shell, open_process_args_in can be used as a more robust and more efficient alternative to open_process_in.

val open_process_out : string -> out_channel

Same as open_process_in, but redirect the standard input of the command to a pipe. Data written to the returned output channel is sent to the standard input of the command. Warning: writes on output channels are buffered, hence be careful to call Stdlib.flush at the right times to ensure correct synchronization. If the command does not need to be run through the shell, open_process_args_out can be used instead of open_process_out.

val open_process : string -> in_channel * out_channel

Same as open_process_out, but redirects both the standard input and standard output of the command to pipes connected to the two returned channels. The input channel is connected to the output of the command, and the output channel to the input of the command. If the command does not need to be run through the shell, open_process_args can be used instead of open_process.

val open_process_full : + int

create_process_env prog args env stdin stdout stderr works as create_process, except that the extra argument env specifies the environment passed to the program.

val open_process_in : string -> Stdlib.in_channel

High-level pipe and process management. This function runs the given command in parallel with the program. The standard output of the command is redirected to a pipe, which can be read via the returned input channel. The command is interpreted by the shell /bin/sh (or cmd.exe on Windows), cf. system. The Filename.quote_command function can be used to quote the command and its arguments as appropriate for the shell being used. If the command does not need to be run through the shell, open_process_args_in can be used as a more robust and more efficient alternative to open_process_in.

val open_process_out : string -> Stdlib.out_channel

Same as open_process_in, but redirect the standard input of the command to a pipe. Data written to the returned output channel is sent to the standard input of the command. Warning: writes on output channels are buffered, hence be careful to call Stdlib.flush at the right times to ensure correct synchronization. If the command does not need to be run through the shell, open_process_args_out can be used instead of open_process_out.

val open_process : string -> Stdlib.in_channel * Stdlib.out_channel

Same as open_process_out, but redirects both the standard input and standard output of the command to pipes connected to the two returned channels. The input channel is connected to the output of the command, and the output channel to the input of the command. If the command does not need to be run through the shell, open_process_args can be used instead of open_process.

val open_process_full : string -> string array -> - in_channel * out_channel * in_channel

Similar to open_process, but the second argument specifies the environment passed to the command. The result is a triple of channels connected respectively to the standard output, standard input, and standard error of the command. If the command does not need to be run through the shell, open_process_args_full can be used instead of open_process_full.

val open_process_args : string -> string array -> in_channel * out_channel

open_process_args prog args runs the program prog with arguments args. Note that the first argument, args.(0), is by convention the filename of the program being executed, just like Sys.argv.(0). The new process executes concurrently with the current process. The standard input and output of the new process are redirected to pipes, which can be respectively read and written via the returned channels. The input channel is connected to the output of the program, and the output channel to the input of the program.

Warning: writes on output channels are buffered, hence be careful to call Stdlib.flush at the right times to ensure correct synchronization.

The executable file prog is searched for in the path. This behaviour changed in 4.12; previously prog was looked up only in the current directory.

The new process has the same environment as the current process.

val open_process_args_in : string -> string array -> in_channel

Same as open_process_args, but redirects only the standard output of the new process.

val open_process_args_out : string -> string array -> out_channel

Same as open_process_args, but redirects only the standard input of the new process.

val open_process_args_full : + Stdlib.in_channel * Stdlib.out_channel * Stdlib.in_channel

Similar to open_process, but the second argument specifies the environment passed to the command. The result is a triple of channels connected respectively to the standard output, standard input, and standard error of the command. If the command does not need to be run through the shell, open_process_args_full can be used instead of open_process_full.

val open_process_args : + string -> + string array -> + Stdlib.in_channel * Stdlib.out_channel

open_process_args prog args runs the program prog with arguments args. Note that the first argument, args.(0), is by convention the filename of the program being executed, just like Sys.argv.(0). The new process executes concurrently with the current process. The standard input and output of the new process are redirected to pipes, which can be respectively read and written via the returned channels. The input channel is connected to the output of the program, and the output channel to the input of the program.

Warning: writes on output channels are buffered, hence be careful to call Stdlib.flush at the right times to ensure correct synchronization.

The executable file prog is searched for in the path. This behaviour changed in 4.12; previously prog was looked up only in the current directory.

The new process has the same environment as the current process.

val open_process_args_in : string -> string array -> Stdlib.in_channel

Same as open_process_args, but redirects only the standard output of the new process.

val open_process_args_out : string -> string array -> Stdlib.out_channel

Same as open_process_args, but redirects only the standard input of the new process.

val open_process_args_full : string -> string array -> string array -> - in_channel * out_channel * in_channel

Similar to open_process_args, but the third argument specifies the environment passed to the new process. The result is a triple of channels connected respectively to the standard output, standard input, and standard error of the program.

val process_in_pid : in_channel -> int

Return the pid of a process opened via open_process_args_in or the pid of the shell opened via open_process_in.

val process_out_pid : out_channel -> int

Return the pid of a process opened via open_process_args_out or the pid of the shell opened via open_process_out.

val process_pid : (in_channel * out_channel) -> int

Return the pid of a process opened via open_process_args or the pid of the shell opened via open_process_args.

val process_full_pid : (in_channel * out_channel * in_channel) -> int

Return the pid of a process opened via open_process_args_full or the pid of the shell opened via open_process_full.

val close_process_in : in_channel -> process_status

Close channels opened by open_process_in, wait for the associated command to terminate, and return its termination status.

val close_process_out : out_channel -> process_status

Close channels opened by open_process_out, wait for the associated command to terminate, and return its termination status.

val close_process : (in_channel * out_channel) -> process_status

Close channels opened by open_process, wait for the associated command to terminate, and return its termination status.

val close_process_full : - (in_channel * out_channel * in_channel) -> + Stdlib.in_channel * Stdlib.out_channel * Stdlib.in_channel

Similar to open_process_args, but the third argument specifies the environment passed to the new process. The result is a triple of channels connected respectively to the standard output, standard input, and standard error of the program.

val process_in_pid : Stdlib.in_channel -> int

Return the pid of a process opened via open_process_args_in or the pid of the shell opened via open_process_in.

val process_out_pid : Stdlib.out_channel -> int

Return the pid of a process opened via open_process_args_out or the pid of the shell opened via open_process_out.

val process_pid : (Stdlib.in_channel * Stdlib.out_channel) -> int

Return the pid of a process opened via open_process_args or the pid of the shell opened via open_process_args.

val process_full_pid : + (Stdlib.in_channel * Stdlib.out_channel * Stdlib.in_channel) -> + int

Return the pid of a process opened via open_process_args_full or the pid of the shell opened via open_process_full.

val close_process_in : Stdlib.in_channel -> process_status

Close channels opened by open_process_in, wait for the associated command to terminate, and return its termination status.

val close_process_out : Stdlib.out_channel -> process_status

Close channels opened by open_process_out, wait for the associated command to terminate, and return its termination status.

val close_process : (Stdlib.in_channel * Stdlib.out_channel) -> process_status

Close channels opened by open_process, wait for the associated command to terminate, and return its termination status.

val close_process_full : + (Stdlib.in_channel * Stdlib.out_channel * Stdlib.in_channel) -> process_status

Close channels opened by open_process_full, wait for the associated command to terminate, and return its termination status.

symlink ?to_dir src dst creates the file dst as a symbolic link to the file src. On Windows, ~to_dir indicates if the symbolic link points to a directory or a file; if omitted, symlink examines src using stat and picks appropriately, if src does not exist then false is assumed (for this reason, it is recommended that the ~to_dir parameter be specified in new code). On Unix, ~to_dir is ignored.

Windows symbolic links are available in Windows Vista onwards. There are some important differences between Windows symlinks and their POSIX counterparts.

Windows symbolic links come in two flavours: directory and regular, which designate whether the symbolic link points to a directory or a file. The type must be correct - a directory symlink which actually points to a file cannot be selected with chdir and a file symlink which actually points to a directory cannot be read or written (note that Cygwin's emulation layer ignores this distinction).

When symbolic links are created to existing targets, this distinction doesn't matter and symlink will automatically create the correct kind of symbolic link. The distinction matters when a symbolic link is created to a non-existent target.

The other caveat is that by default symbolic links are a privileged operation. Administrators will always need to be running elevated (or with UAC disabled) and by default normal user accounts need to be granted the SeCreateSymbolicLinkPrivilege via Local Security Policy (secpol.msc) or via Active Directory.

has_symlink can be used to check that a process is able to create symbolic links.

Returns true if the user is able to create symbolic links. On Windows, this indicates that the user not only has the SeCreateSymbolicLinkPrivilege but is also running elevated, if necessary. On other platforms, this is simply indicates that the symlink system call is available.

Read the contents of a symbolic link.

Polling

val select : file_descr list -> file_descr list -> @@ -83,4 +88,7 @@ file_descr -> socket_optint_option -> int option -> - unit

Same as setsockopt for a socket option whose value is an int option.

val getsockopt_float : file_descr -> socket_float_option -> float

Same as getsockopt for a socket option whose value is a floating-point number.

val setsockopt_float : file_descr -> socket_float_option -> float -> unit

Same as setsockopt for a socket option whose value is a floating-point number.

val getsockopt_error : file_descr -> error option

Return the error condition associated with the given socket, and clear it.

High-level network connection functions

val open_connection : sockaddr -> in_channel * out_channel

Connect to a server at the given address. Return a pair of buffered channels connected to the server. Remember to call Stdlib.flush on the output channel at the right times to ensure correct synchronization.

The two channels returned by open_connection share a descriptor to a socket. Therefore, when the connection is over, you should call Stdlib.close_out on the output channel, which will also close the underlying socket. Do not call Stdlib.close_in on the input channel; it will be collected by the GC eventually.

val shutdown_connection : in_channel -> unit

``Shut down'' a connection established with open_connection; that is, transmit an end-of-file condition to the server reading on the other side of the connection. This does not close the socket and the channels used by the connection. See Unix.open_connection for how to close them once the connection is over.

val establish_server : (in_channel -> out_channel -> unit) -> sockaddr -> unit

Establish a server on the given address. The function given as first argument is called for each connection with two buffered channels connected to the client. A new process is created for each connection. The function establish_server never returns normally.

The two channels given to the function share a descriptor to a socket. The function does not need to close the channels, since this occurs automatically when the function returns. If the function prefers explicit closing, it should close the output channel using Stdlib.close_out and leave the input channel unclosed, for reasons explained in Unix.in_channel_of_descr.

Host and protocol databases

type host_entry = {
  1. h_name : string;
  2. h_aliases : string array;
  3. h_addrtype : socket_domain;
  4. h_addr_list : inet_addr array;
}

Structure of entries in the hosts database.

type protocol_entry = {
  1. p_name : string;
  2. p_aliases : string array;
  3. p_proto : int;
}

Structure of entries in the protocols database.

type service_entry = {
  1. s_name : string;
  2. s_aliases : string array;
  3. s_port : int;
  4. s_proto : string;
}

Structure of entries in the services database.

val gethostname : unit -> string

Return the name of the local host.

val gethostbyname : string -> host_entry

Find an entry in hosts with the given name.

val gethostbyaddr : inet_addr -> host_entry

Find an entry in hosts with the given address.

val getprotobyname : string -> protocol_entry

Find an entry in protocols with the given name.

val getprotobynumber : int -> protocol_entry

Find an entry in protocols with the given protocol number.

val getservbyname : string -> string -> service_entry

Find an entry in services with the given name.

val getservbyport : int -> string -> service_entry

Find an entry in services with the given service number.

type addr_info = {
  1. ai_family : socket_domain;
    (*

    Socket domain

    *)
  2. ai_socktype : socket_type;
    (*

    Socket type

    *)
  3. ai_protocol : int;
    (*

    Socket protocol number

    *)
  4. ai_addr : sockaddr;
    (*

    Address

    *)
  5. ai_canonname : string;
    (*

    Canonical host name

    *)
}

Address information returned by getaddrinfo.

type getaddrinfo_option =
  1. | AI_FAMILY of socket_domain
    (*

    Impose the given socket domain

    *)
  2. | AI_SOCKTYPE of socket_type
    (*

    Impose the given socket type

    *)
  3. | AI_PROTOCOL of int
    (*

    Impose the given protocol

    *)
  4. | AI_NUMERICHOST
    (*

    Do not call name resolver, expect numeric IP address

    *)
  5. | AI_CANONNAME
    (*

    Fill the ai_canonname field of the result

    *)
  6. | AI_PASSIVE
    (*

    Set address to ``any'' address for use with bind

    *)

Options to getaddrinfo.

val getaddrinfo : string -> string -> getaddrinfo_option list -> addr_info list

getaddrinfo host service opts returns a list of addr_info records describing socket parameters and addresses suitable for communicating with the given host and service. The empty list is returned if the host or service names are unknown, or the constraints expressed in opts cannot be satisfied.

host is either a host name or the string representation of an IP address. host can be given as the empty string; in this case, the ``any'' address or the ``loopback'' address are used, depending whether opts contains AI_PASSIVE. service is either a service name or the string representation of a port number. service can be given as the empty string; in this case, the port field of the returned addresses is set to 0. opts is a possibly empty list of options that allows the caller to force a particular socket domain (e.g. IPv6 only or IPv4 only) or a particular socket type (e.g. TCP only or UDP only).

type name_info = {
  1. ni_hostname : string;
    (*

    Name or IP address of host

    *)
  2. ni_service : string;
    (*

    Name of service or port number

    *)
}

Host and service information returned by getnameinfo.

type getnameinfo_option =
  1. | NI_NOFQDN
    (*

    Do not qualify local host names

    *)
  2. | NI_NUMERICHOST
    (*

    Always return host as IP address

    *)
  3. | NI_NAMEREQD
    (*

    Fail if host name cannot be determined

    *)
  4. | NI_NUMERICSERV
    (*

    Always return service as port number

    *)
  5. | NI_DGRAM
    (*

    Consider the service as UDP-based instead of the default TCP

    *)

Options to getnameinfo.

val getnameinfo : sockaddr -> getnameinfo_option list -> name_info

getnameinfo addr opts returns the host name and service name corresponding to the socket address addr. opts is a possibly empty list of options that governs how these names are obtained.

Terminal interface

The following functions implement the POSIX standard terminal interface. They provide control over asynchronous communication ports and pseudo-terminals. Refer to the termios man page for a complete description.

type terminal_io = {
  1. mutable c_ignbrk : bool;
    (*

    Ignore the break condition.

    *)
  2. mutable c_brkint : bool;
    (*

    Signal interrupt on break condition.

    *)
  3. mutable c_ignpar : bool;
    (*

    Ignore characters with parity errors.

    *)
  4. mutable c_parmrk : bool;
    (*

    Mark parity errors.

    *)
  5. mutable c_inpck : bool;
    (*

    Enable parity check on input.

    *)
  6. mutable c_istrip : bool;
    (*

    Strip 8th bit on input characters.

    *)
  7. mutable c_inlcr : bool;
    (*

    Map NL to CR on input.

    *)
  8. mutable c_igncr : bool;
    (*

    Ignore CR on input.

    *)
  9. mutable c_icrnl : bool;
    (*

    Map CR to NL on input.

    *)
  10. mutable c_ixon : bool;
    (*

    Recognize XON/XOFF characters on input.

    *)
  11. mutable c_ixoff : bool;
    (*

    Emit XON/XOFF chars to control input flow.

    *)
  12. mutable c_opost : bool;
    (*

    Enable output processing.

    *)
  13. mutable c_obaud : int;
    (*

    Output baud rate (0 means close connection).

    *)
  14. mutable c_ibaud : int;
    (*

    Input baud rate.

    *)
  15. mutable c_csize : int;
    (*

    Number of bits per character (5-8).

    *)
  16. mutable c_cstopb : int;
    (*

    Number of stop bits (1-2).

    *)
  17. mutable c_cread : bool;
    (*

    Reception is enabled.

    *)
  18. mutable c_parenb : bool;
    (*

    Enable parity generation and detection.

    *)
  19. mutable c_parodd : bool;
    (*

    Specify odd parity instead of even.

    *)
  20. mutable c_hupcl : bool;
    (*

    Hang up on last close.

    *)
  21. mutable c_clocal : bool;
    (*

    Ignore modem status lines.

    *)
  22. mutable c_isig : bool;
    (*

    Generate signal on INTR, QUIT, SUSP.

    *)
  23. mutable c_icanon : bool;
    (*

    Enable canonical processing (line buffering and editing)

    *)
  24. mutable c_noflsh : bool;
    (*

    Disable flush after INTR, QUIT, SUSP.

    *)
  25. mutable c_echo : bool;
    (*

    Echo input characters.

    *)
  26. mutable c_echoe : bool;
    (*

    Echo ERASE (to erase previous character).

    *)
  27. mutable c_echok : bool;
    (*

    Echo KILL (to erase the current line).

    *)
  28. mutable c_echonl : bool;
    (*

    Echo NL even if c_echo is not set.

    *)
  29. mutable c_vintr : char;
    (*

    Interrupt character (usually ctrl-C).

    *)
  30. mutable c_vquit : char;
    (*

    Quit character (usually ctrl-\).

    *)
  31. mutable c_verase : char;
    (*

    Erase character (usually DEL or ctrl-H).

    *)
  32. mutable c_vkill : char;
    (*

    Kill line character (usually ctrl-U).

    *)
  33. mutable c_veof : char;
    (*

    End-of-file character (usually ctrl-D).

    *)
  34. mutable c_veol : char;
    (*

    Alternate end-of-line char. (usually none).

    *)
  35. mutable c_vmin : int;
    (*

    Minimum number of characters to read before the read request is satisfied.

    *)
  36. mutable c_vtime : int;
    (*

    Maximum read wait (in 0.1s units).

    *)
  37. mutable c_vstart : char;
    (*

    Start character (usually ctrl-Q).

    *)
  38. mutable c_vstop : char;
    (*

    Stop character (usually ctrl-S).

    *)
}
val tcgetattr : file_descr -> terminal_io

Return the status of the terminal referred to by the given file descriptor.

type setattr_when =
  1. | TCSANOW
  2. | TCSADRAIN
  3. | TCSAFLUSH
val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit

Set the status of the terminal referred to by the given file descriptor. The second argument indicates when the status change takes place: immediately (TCSANOW), when all pending output has been transmitted (TCSADRAIN), or after flushing all input that has been received but not read (TCSAFLUSH). TCSADRAIN is recommended when changing the output parameters; TCSAFLUSH, when changing the input parameters.

val tcsendbreak : file_descr -> int -> unit

Send a break condition on the given file descriptor. The second argument is the duration of the break, in 0.1s units; 0 means standard duration (0.25s).

val tcdrain : file_descr -> unit

Waits until all output written on the given file descriptor has been transmitted.

type flush_queue =
  1. | TCIFLUSH
  2. | TCOFLUSH
  3. | TCIOFLUSH
val tcflush : file_descr -> flush_queue -> unit

Discard data written on the given file descriptor but not yet transmitted, or data received but not yet read, depending on the second argument: TCIFLUSH flushes data received but not read, TCOFLUSH flushes data written but not transmitted, and TCIOFLUSH flushes both.

type flow_action =
  1. | TCOOFF
  2. | TCOON
  3. | TCIOFF
  4. | TCION
val tcflow : file_descr -> flow_action -> unit

Suspend or restart reception or transmission of data on the given file descriptor, depending on the second argument: TCOOFF suspends output, TCOON restarts output, TCIOFF transmits a STOP character to suspend input, and TCION transmits a START character to restart input.

val setsid : unit -> int

Put the calling process in a new session and detach it from its controlling terminal.

+ unit

Same as setsockopt for a socket option whose value is an int option.

val getsockopt_float : file_descr -> socket_float_option -> float

Same as getsockopt for a socket option whose value is a floating-point number.

val setsockopt_float : file_descr -> socket_float_option -> float -> unit

Same as setsockopt for a socket option whose value is a floating-point number.

val getsockopt_error : file_descr -> error option

Return the error condition associated with the given socket, and clear it.

High-level network connection functions

val open_connection : sockaddr -> Stdlib.in_channel * Stdlib.out_channel

Connect to a server at the given address. Return a pair of buffered channels connected to the server. Remember to call Stdlib.flush on the output channel at the right times to ensure correct synchronization.

The two channels returned by open_connection share a descriptor to a socket. Therefore, when the connection is over, you should call Stdlib.close_out on the output channel, which will also close the underlying socket. Do not call Stdlib.close_in on the input channel; it will be collected by the GC eventually.

val shutdown_connection : Stdlib.in_channel -> unit

``Shut down'' a connection established with open_connection; that is, transmit an end-of-file condition to the server reading on the other side of the connection. This does not close the socket and the channels used by the connection. See Unix.open_connection for how to close them once the connection is over.

val establish_server : + (Stdlib.in_channel -> Stdlib.out_channel -> unit) -> + sockaddr -> + unit

Establish a server on the given address. The function given as first argument is called for each connection with two buffered channels connected to the client. A new process is created for each connection. The function establish_server never returns normally.

The two channels given to the function share a descriptor to a socket. The function does not need to close the channels, since this occurs automatically when the function returns. If the function prefers explicit closing, it should close the output channel using Stdlib.close_out and leave the input channel unclosed, for reasons explained in Unix.in_channel_of_descr.

Host and protocol databases

type host_entry = {
  1. h_name : string;
  2. h_aliases : string array;
  3. h_addrtype : socket_domain;
  4. h_addr_list : inet_addr array;
}

Structure of entries in the hosts database.

type protocol_entry = {
  1. p_name : string;
  2. p_aliases : string array;
  3. p_proto : int;
}

Structure of entries in the protocols database.

type service_entry = {
  1. s_name : string;
  2. s_aliases : string array;
  3. s_port : int;
  4. s_proto : string;
}

Structure of entries in the services database.

val gethostname : unit -> string

Return the name of the local host.

val gethostbyname : string -> host_entry

Find an entry in hosts with the given name.

val gethostbyaddr : inet_addr -> host_entry

Find an entry in hosts with the given address.

val getprotobyname : string -> protocol_entry

Find an entry in protocols with the given name.

val getprotobynumber : int -> protocol_entry

Find an entry in protocols with the given protocol number.

val getservbyname : string -> string -> service_entry

Find an entry in services with the given name.

val getservbyport : int -> string -> service_entry

Find an entry in services with the given service number.

type addr_info = {
  1. ai_family : socket_domain;
    (*

    Socket domain

    *)
  2. ai_socktype : socket_type;
    (*

    Socket type

    *)
  3. ai_protocol : int;
    (*

    Socket protocol number

    *)
  4. ai_addr : sockaddr;
    (*

    Address

    *)
  5. ai_canonname : string;
    (*

    Canonical host name

    *)
}

Address information returned by getaddrinfo.

type getaddrinfo_option =
  1. | AI_FAMILY of socket_domain
    (*

    Impose the given socket domain

    *)
  2. | AI_SOCKTYPE of socket_type
    (*

    Impose the given socket type

    *)
  3. | AI_PROTOCOL of int
    (*

    Impose the given protocol

    *)
  4. | AI_NUMERICHOST
    (*

    Do not call name resolver, expect numeric IP address

    *)
  5. | AI_CANONNAME
    (*

    Fill the ai_canonname field of the result

    *)
  6. | AI_PASSIVE
    (*

    Set address to ``any'' address for use with bind

    *)

Options to getaddrinfo.

val getaddrinfo : string -> string -> getaddrinfo_option list -> addr_info list

getaddrinfo host service opts returns a list of addr_info records describing socket parameters and addresses suitable for communicating with the given host and service. The empty list is returned if the host or service names are unknown, or the constraints expressed in opts cannot be satisfied.

host is either a host name or the string representation of an IP address. host can be given as the empty string; in this case, the ``any'' address or the ``loopback'' address are used, depending whether opts contains AI_PASSIVE. service is either a service name or the string representation of a port number. service can be given as the empty string; in this case, the port field of the returned addresses is set to 0. opts is a possibly empty list of options that allows the caller to force a particular socket domain (e.g. IPv6 only or IPv4 only) or a particular socket type (e.g. TCP only or UDP only).

type name_info = {
  1. ni_hostname : string;
    (*

    Name or IP address of host

    *)
  2. ni_service : string;
    (*

    Name of service or port number

    *)
}

Host and service information returned by getnameinfo.

type getnameinfo_option =
  1. | NI_NOFQDN
    (*

    Do not qualify local host names

    *)
  2. | NI_NUMERICHOST
    (*

    Always return host as IP address

    *)
  3. | NI_NAMEREQD
    (*

    Fail if host name cannot be determined

    *)
  4. | NI_NUMERICSERV
    (*

    Always return service as port number

    *)
  5. | NI_DGRAM
    (*

    Consider the service as UDP-based instead of the default TCP

    *)

Options to getnameinfo.

val getnameinfo : sockaddr -> getnameinfo_option list -> name_info

getnameinfo addr opts returns the host name and service name corresponding to the socket address addr. opts is a possibly empty list of options that governs how these names are obtained.

Terminal interface

The following functions implement the POSIX standard terminal interface. They provide control over asynchronous communication ports and pseudo-terminals. Refer to the termios man page for a complete description.

type terminal_io = {
  1. mutable c_ignbrk : bool;
    (*

    Ignore the break condition.

    *)
  2. mutable c_brkint : bool;
    (*

    Signal interrupt on break condition.

    *)
  3. mutable c_ignpar : bool;
    (*

    Ignore characters with parity errors.

    *)
  4. mutable c_parmrk : bool;
    (*

    Mark parity errors.

    *)
  5. mutable c_inpck : bool;
    (*

    Enable parity check on input.

    *)
  6. mutable c_istrip : bool;
    (*

    Strip 8th bit on input characters.

    *)
  7. mutable c_inlcr : bool;
    (*

    Map NL to CR on input.

    *)
  8. mutable c_igncr : bool;
    (*

    Ignore CR on input.

    *)
  9. mutable c_icrnl : bool;
    (*

    Map CR to NL on input.

    *)
  10. mutable c_ixon : bool;
    (*

    Recognize XON/XOFF characters on input.

    *)
  11. mutable c_ixoff : bool;
    (*

    Emit XON/XOFF chars to control input flow.

    *)
  12. mutable c_opost : bool;
    (*

    Enable output processing.

    *)
  13. mutable c_obaud : int;
    (*

    Output baud rate (0 means close connection).

    *)
  14. mutable c_ibaud : int;
    (*

    Input baud rate.

    *)
  15. mutable c_csize : int;
    (*

    Number of bits per character (5-8).

    *)
  16. mutable c_cstopb : int;
    (*

    Number of stop bits (1-2).

    *)
  17. mutable c_cread : bool;
    (*

    Reception is enabled.

    *)
  18. mutable c_parenb : bool;
    (*

    Enable parity generation and detection.

    *)
  19. mutable c_parodd : bool;
    (*

    Specify odd parity instead of even.

    *)
  20. mutable c_hupcl : bool;
    (*

    Hang up on last close.

    *)
  21. mutable c_clocal : bool;
    (*

    Ignore modem status lines.

    *)
  22. mutable c_isig : bool;
    (*

    Generate signal on INTR, QUIT, SUSP.

    *)
  23. mutable c_icanon : bool;
    (*

    Enable canonical processing (line buffering and editing)

    *)
  24. mutable c_noflsh : bool;
    (*

    Disable flush after INTR, QUIT, SUSP.

    *)
  25. mutable c_echo : bool;
    (*

    Echo input characters.

    *)
  26. mutable c_echoe : bool;
    (*

    Echo ERASE (to erase previous character).

    *)
  27. mutable c_echok : bool;
    (*

    Echo KILL (to erase the current line).

    *)
  28. mutable c_echonl : bool;
    (*

    Echo NL even if c_echo is not set.

    *)
  29. mutable c_vintr : char;
    (*

    Interrupt character (usually ctrl-C).

    *)
  30. mutable c_vquit : char;
    (*

    Quit character (usually ctrl-\).

    *)
  31. mutable c_verase : char;
    (*

    Erase character (usually DEL or ctrl-H).

    *)
  32. mutable c_vkill : char;
    (*

    Kill line character (usually ctrl-U).

    *)
  33. mutable c_veof : char;
    (*

    End-of-file character (usually ctrl-D).

    *)
  34. mutable c_veol : char;
    (*

    Alternate end-of-line char. (usually none).

    *)
  35. mutable c_vmin : int;
    (*

    Minimum number of characters to read before the read request is satisfied.

    *)
  36. mutable c_vtime : int;
    (*

    Maximum read wait (in 0.1s units).

    *)
  37. mutable c_vstart : char;
    (*

    Start character (usually ctrl-Q).

    *)
  38. mutable c_vstop : char;
    (*

    Stop character (usually ctrl-S).

    *)
}
val tcgetattr : file_descr -> terminal_io

Return the status of the terminal referred to by the given file descriptor.

type setattr_when =
  1. | TCSANOW
  2. | TCSADRAIN
  3. | TCSAFLUSH
val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit

Set the status of the terminal referred to by the given file descriptor. The second argument indicates when the status change takes place: immediately (TCSANOW), when all pending output has been transmitted (TCSADRAIN), or after flushing all input that has been received but not read (TCSAFLUSH). TCSADRAIN is recommended when changing the output parameters; TCSAFLUSH, when changing the input parameters.

val tcsendbreak : file_descr -> int -> unit

Send a break condition on the given file descriptor. The second argument is the duration of the break, in 0.1s units; 0 means standard duration (0.25s).

val tcdrain : file_descr -> unit

Waits until all output written on the given file descriptor has been transmitted.

type flush_queue =
  1. | TCIFLUSH
  2. | TCOFLUSH
  3. | TCIOFLUSH
val tcflush : file_descr -> flush_queue -> unit

Discard data written on the given file descriptor but not yet transmitted, or data received but not yet read, depending on the second argument: TCIFLUSH flushes data received but not read, TCOFLUSH flushes data written but not transmitted, and TCIOFLUSH flushes both.

type flow_action =
  1. | TCOOFF
  2. | TCOON
  3. | TCIOFF
  4. | TCION
val tcflow : file_descr -> flow_action -> unit

Suspend or restart reception or transmission of data on the given file descriptor, depending on the second argument: TCOOFF suspends output, TCOON restarts output, TCIOFF transmits a STOP character to suspend input, and TCION transmits a START character to restart input.

val setsid : unit -> int

Put the calling process in a new session and detach it from its controlling terminal.

diff --git a/tiny_httpd/Tiny_httpd/index.html b/tiny_httpd/Tiny_httpd/index.html index c77babca..0d54f48f 100644 --- a/tiny_httpd/Tiny_httpd/index.html +++ b/tiny_httpd/Tiny_httpd/index.html @@ -127,7 +127,7 @@ echo: ?new_thread:((unit -> unit) -> unit) -> ?addr:string -> ?port:int -> - ?sock:Unix.file_descr -> + ?sock:Unix.file_descr -> ?head_middlewares:Head_middleware.t list -> ?middlewares:([ `Encoding | `Stage of int ] * Middleware.t) list -> unit -> diff --git a/tiny_httpd/Tiny_httpd_core/IO/Input/index.html b/tiny_httpd/Tiny_httpd_core/IO/Input/index.html index 793c2b2e..6701058b 100644 --- a/tiny_httpd/Tiny_httpd_core/IO/Input/index.html +++ b/tiny_httpd/Tiny_httpd_core/IO/Input/index.html @@ -19,7 +19,7 @@ ?close_noerr:bool -> closed:bool ref -> buf:Slice.t -> - Unix.file_descr -> + Unix.file_descr -> t
val of_slice : Slice.t -> t
val input : t -> bytes -> int -> int -> int

Read into the given slice.

val close : < close : unit -> unit.. > -> unit

Close the channel.

val really_input : t -> bytes -> int -> int -> unit

Read exactly len bytes.

val iter_slice : (Slice.t -> unit) -> t -> unit
val iter : (bytes -> int -> int -> unit) -> t -> unit
val to_chan : out_channel -> t -> unit
val to_chan' : Iostream.Out.t -> t -> unit
val read_all_using : buf:Buf.t -> t -> string
val read_exactly_ : too_short:(unit -> unit) -> t -> bytes -> int -> unit

Read n bytes from the input into bytes.

val read_line_into : t -> buf:Buf.t -> unit

read a line into the buffer, after clearing it.

val read_line_using : buf:Buf.t -> t -> string
val read_line_using_opt : buf:Buf.t -> t -> string option
val reading_exactly_ : skip_on_close:bool -> close_rec:bool -> diff --git a/tiny_httpd/Tiny_httpd_core/IO/Output/index.html b/tiny_httpd/Tiny_httpd_core/IO/Output/index.html index 8e45ffd0..d75d499d 100644 --- a/tiny_httpd/Tiny_httpd_core/IO/Output/index.html +++ b/tiny_httpd/Tiny_httpd_core/IO/Output/index.html @@ -17,5 +17,5 @@ ?flags:open_flag list -> string -> (t_seekable -> 'a) -> - 'a
val output_char : t -> char -> unit

Output a single char

val output : t -> bytes -> int -> int -> unit

Write the slice of bytes.

val close : t -> unit

Close the stream. Idempotent.

val flush : t -> unit

Ensure the bytes written so far are indeed written to the underlying storage/network socket/… and are not just sitting in a buffer.

val output_string : t -> string -> unit

Output the whole string.

val output_line : t -> string -> unit

Output the whole string followed by '\n'.

val output_lines : t -> string Stdlib.Seq.t -> unit

Output a series of lines, each terminated by '\n'.

val output_int : t -> int -> unit

Output an integer in decimal notation.

val tee : t list -> t

tee ocs is an output that accepts bytes and writes them to every output in ocs. When closed, it closes all elements of oc.

val map_char : (char -> char) -> t -> t

Transform the stream byte by byte

class of_unix_fd : ?close_noerr:bool option -> closed:bool ref -> buf:Slice.t -> Unix.file_descr -> + 'a
val output_char : t -> char -> unit

Output a single char

val output : t -> bytes -> int -> int -> unit

Write the slice of bytes.

val close : t -> unit

Close the stream. Idempotent.

val flush : t -> unit

Ensure the bytes written so far are indeed written to the underlying storage/network socket/… and are not just sitting in a buffer.

val output_string : t -> string -> unit

Output the whole string.

val output_line : t -> string -> unit

Output the whole string followed by '\n'.

val output_lines : t -> string Stdlib.Seq.t -> unit

Output a series of lines, each terminated by '\n'.

val output_int : t -> int -> unit

Output an integer in decimal notation.

val tee : t list -> t

tee ocs is an output that accepts bytes and writes them to every output in ocs. When closed, it closes all elements of oc.

val map_char : (char -> char) -> t -> t

Transform the stream byte by byte

class of_unix_fd : ?close_noerr:bool option -> closed:bool ref -> buf:Slice.t -> Unix.file_descr -> t
val output_buf : t -> Buf.t -> unit
val chunk_encoding : ?buf:Buf.t -> close_rec:bool -> t -> t

chunk_encoding oc makes a new channel that outputs its content into oc in chunk encoding form.

diff --git a/tiny_httpd/Tiny_httpd_core/IO/TCP_server/index.html b/tiny_httpd/Tiny_httpd_core/IO/TCP_server/index.html index 3868501e..55505b4e 100644 --- a/tiny_httpd/Tiny_httpd_core/IO/TCP_server/index.html +++ b/tiny_httpd/Tiny_httpd_core/IO/TCP_server/index.html @@ -1,2 +1,2 @@ -TCP_server (tiny_httpd.Tiny_httpd_core.IO.TCP_server)

Module IO.TCP_server

A TCP server abstraction.

type conn_handler = {
  1. handle : client_addr:Unix.sockaddr -> Input.t -> Output.t -> unit;
    (*

    Handle client connection

    *)
}
type t = {
  1. endpoint : unit -> string * int;
    (*

    Endpoint we listen on. This can only be called from within serve.

    *)
  2. active_connections : unit -> int;
    (*

    Number of connections currently active

    *)
  3. running : unit -> bool;
    (*

    Is the server currently running?

    *)
  4. stop : unit -> unit;
    (*

    Ask the server to stop. This might not take effect immediately, and is idempotent. After this server.running() must return false.

    *)
}

A running TCP server.

This contains some functions that provide information about the running server, including whether it's active (as opposed to stopped), a function to stop it, and statistics about the number of connections.

type builder = {
  1. serve : after_init:(t -> unit) -> handle:conn_handler -> unit -> unit;
    (*

    Blocking call to listen for incoming connections and handle them. Uses the connection handler handle to handle individual client connections in individual threads/fibers/tasks.

    • parameter after_init

      is called once with the server after the server has started.

    *)
}

A TCP server builder implementation.

Calling builder.serve ~after_init ~handle () starts a new TCP server on an unspecified endpoint (most likely coming from the function returning this builder) and returns the running server.

+TCP_server (tiny_httpd.Tiny_httpd_core.IO.TCP_server)

Module IO.TCP_server

A TCP server abstraction.

type conn_handler = {
  1. handle : client_addr:Unix.sockaddr -> Input.t -> Output.t -> unit;
    (*

    Handle client connection

    *)
}
type t = {
  1. endpoint : unit -> string * int;
    (*

    Endpoint we listen on. This can only be called from within serve.

    *)
  2. active_connections : unit -> int;
    (*

    Number of connections currently active

    *)
  3. running : unit -> bool;
    (*

    Is the server currently running?

    *)
  4. stop : unit -> unit;
    (*

    Ask the server to stop. This might not take effect immediately, and is idempotent. After this server.running() must return false.

    *)
}

A running TCP server.

This contains some functions that provide information about the running server, including whether it's active (as opposed to stopped), a function to stop it, and statistics about the number of connections.

type builder = {
  1. serve : after_init:(t -> unit) -> handle:conn_handler -> unit -> unit;
    (*

    Blocking call to listen for incoming connections and handle them. Uses the connection handler handle to handle individual client connections in individual threads/fibers/tasks.

    • parameter after_init

      is called once with the server after the server has started.

    *)
}

A TCP server builder implementation.

Calling builder.serve ~after_init ~handle () starts a new TCP server on an unspecified endpoint (most likely coming from the function returning this builder) and returns the running server.

diff --git a/tiny_httpd/Tiny_httpd_core/Pool/Raw/index.html b/tiny_httpd/Tiny_httpd_core/Pool/Raw/index.html index 189aeb0b..bb728c64 100644 --- a/tiny_httpd/Tiny_httpd_core/Pool/Raw/index.html +++ b/tiny_httpd/Tiny_httpd_core/Pool/Raw/index.html @@ -1,2 +1,2 @@ -Raw (tiny_httpd.Tiny_httpd_core.Pool.Raw)

Module Pool.Raw

Low level control over the pool. This is easier to get wrong (e.g. releasing the same resource twice) so use with caution.

val acquire : 'a t -> 'a
val release : 'a t -> 'a -> unit
+Raw (tiny_httpd.Tiny_httpd_core.Pool.Raw)

Module Pool.Raw

Low level control over the pool. This is easier to get wrong (e.g. releasing the same resource twice) so use with caution.

val acquire : 'a t -> 'a
val release : 'a t -> 'a -> unit
diff --git a/tiny_httpd/Tiny_httpd_core/Request/index.html b/tiny_httpd/Tiny_httpd_core/Request/index.html index 8bd23232..66e113f5 100644 --- a/tiny_httpd/Tiny_httpd_core/Request/index.html +++ b/tiny_httpd/Tiny_httpd_core/Request/index.html @@ -1,5 +1,5 @@ -Request (tiny_httpd.Tiny_httpd_core.Request)

Module Tiny_httpd_core.Request

Requests

Requests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.

type 'body t = private {
  1. meth : Meth.t;
    (*

    HTTP method for this request.

    *)
  2. host : string;
    (*

    Host header, mandatory. It can also be found in headers.

    *)
  3. client_addr : Unix.sockaddr;
    (*

    Client address. Available since 0.14.

    *)
  4. headers : Headers.t;
    (*

    List of headers.

    *)
  5. mutable meta : Hmap.t;
    (*

    Metadata.

    • since 0.17
    *)
  6. http_version : int * int;
    (*

    HTTP version. This should be either 1, 0 or 1, 1.

    *)
  7. path : string;
    (*

    Full path of the requested URL.

    *)
  8. path_components : string list;
    (*

    Components of the path of the requested URL.

    *)
  9. query : (string * string) list;
    (*

    Query part of the requested URL.

    *)
  10. body : 'body;
    (*

    Body of the request.

    *)
  11. start_time : float;
    (*

    Obtained via get_time_s in create

    • since 0.11
    *)
}

A request with method, path, host, headers, and a body, sent by a client.

The body is polymorphic because the request goes through several transformations. First it has no body, as only the request and headers are read; then it has a stream body; then the body might be entirely read as a string via read_body_full.

  • since 0.6 The field [query] was added and contains the query parameters in ["?foo=bar,x=y"]
  • since 0.6 The field [path_components] is the part of the path that precedes [query] and is split on ["/"].
  • since 0.11 the type is a private alias
  • since 0.11 the field [start_time] was added
val add_meta : _ t -> 'a Hmap.key -> 'a -> unit

Add metadata

  • since 0.17
val get_meta : _ t -> 'a Hmap.key -> 'a option

Get metadata

  • since 0.17
val get_meta_exn : _ t -> 'a Hmap.key -> 'a

Like get_meta but can fail

  • raises Invalid_argument

    if not present

  • since 0.17
val pp_with : +Request (tiny_httpd.Tiny_httpd_core.Request)

Module Tiny_httpd_core.Request

Requests

Requests are sent by a client, e.g. a web browser or cURL. From the point of view of the server, they're inputs.

type 'body t = private {
  1. meth : Meth.t;
    (*

    HTTP method for this request.

    *)
  2. host : string;
    (*

    Host header, mandatory. It can also be found in headers.

    *)
  3. client_addr : Unix.sockaddr;
    (*

    Client address. Available since 0.14.

    *)
  4. headers : Headers.t;
    (*

    List of headers.

    *)
  5. mutable meta : Hmap.t;
    (*

    Metadata.

    • since 0.17
    *)
  6. http_version : int * int;
    (*

    HTTP version. This should be either 1, 0 or 1, 1.

    *)
  7. path : string;
    (*

    Full path of the requested URL.

    *)
  8. path_components : string list;
    (*

    Components of the path of the requested URL.

    *)
  9. query : (string * string) list;
    (*

    Query part of the requested URL.

    *)
  10. body : 'body;
    (*

    Body of the request.

    *)
  11. start_time : float;
    (*

    Obtained via get_time_s in create

    • since 0.11
    *)
}

A request with method, path, host, headers, and a body, sent by a client.

The body is polymorphic because the request goes through several transformations. First it has no body, as only the request and headers are read; then it has a stream body; then the body might be entirely read as a string via read_body_full.

  • since 0.6 The field [query] was added and contains the query parameters in ["?foo=bar,x=y"]
  • since 0.6 The field [path_components] is the part of the path that precedes [query] and is split on ["/"].
  • since 0.11 the type is a private alias
  • since 0.11 the field [start_time] was added
val add_meta : _ t -> 'a Hmap.key -> 'a -> unit

Add metadata

  • since 0.17
val get_meta : _ t -> 'a Hmap.key -> 'a option

Get metadata

  • since 0.17
val get_meta_exn : _ t -> 'a Hmap.key -> 'a

Like get_meta but can fail

  • raises Invalid_argument

    if not present

  • since 0.17
val pp_with : ?mask_header:(string -> bool) -> ?headers_to_mask:string list -> ?show_query:bool -> @@ -7,7 +7,7 @@ unit -> Stdlib.Format.formatter -> 'body t -> - unit

Pretty print the request. The exact format of this printing is not specified.

  • parameter mask_header

    function which is given each header name. If it returns true, the header's value is masked. The presence of the header is still printed. Default fun _ -> false.

  • parameter headers_to_mask

    a list of headers masked by default. Default is "authorization"; "cookie". @show_query if true (default true), the query part of the request is shown.

  • parameter pp_body

    body printer (default prints "?" instead of the body, which works even for stream bodies)

val pp : Stdlib.Format.formatter -> string t -> unit

Pretty print the request and its body. The exact format of this printing is not specified.

val pp_ : Stdlib.Format.formatter -> _ t -> unit

Pretty print the request without its body. The exact format of this printing is not specified.

val headers : _ t -> Headers.t

List of headers of the request, including "Host".

val get_header : ?f:(string -> string) -> _ t -> string -> string option

get_header req h looks up header h in req. It returns None if the header is not present. This is case insensitive and should be used rather than looking up h verbatim in headers.

val get_header_int : _ t -> string -> int option

Same as get_header but also performs a string to integer conversion.

val set_header : string -> string -> 'a t -> 'a t

set_header k v req sets k: v in the request req's headers.

val remove_header : string -> 'a t -> 'a t

Remove one instance of this header.

  • since 0.17
val update_headers : (Headers.t -> Headers.t) -> 'a t -> 'a t

Modify headers using the given function.

  • since 0.11
val set_body : 'a -> _ t -> 'a t

set_body b req returns a new query whose body is b.

  • since 0.11
val host : _ t -> string

Host field of the request. It also appears in the headers.

val client_addr : _ t -> Unix.sockaddr

Client address of the request.

  • since 0.16
val meth : _ t -> Meth.t

Method for the request.

val path : _ t -> string

Request path.

val query : _ t -> (string * string) list

Decode the query part of the path field.

  • since 0.4
val body : 'b t -> 'b

Request body, possibly empty.

val start_time : _ t -> float

time stamp (from Unix.gettimeofday) after parsing the first line of the request

  • since 0.11
val limit_body_size : + unit

Pretty print the request. The exact format of this printing is not specified.

  • parameter mask_header

    function which is given each header name. If it returns true, the header's value is masked. The presence of the header is still printed. Default fun _ -> false.

  • parameter headers_to_mask

    a list of headers masked by default. Default is "authorization"; "cookie". @show_query if true (default true), the query part of the request is shown.

  • parameter pp_body

    body printer (default prints "?" instead of the body, which works even for stream bodies)

val pp : Stdlib.Format.formatter -> string t -> unit

Pretty print the request and its body. The exact format of this printing is not specified.

val pp_ : Stdlib.Format.formatter -> _ t -> unit

Pretty print the request without its body. The exact format of this printing is not specified.

val headers : _ t -> Headers.t

List of headers of the request, including "Host".

val get_header : ?f:(string -> string) -> _ t -> string -> string option

get_header req h looks up header h in req. It returns None if the header is not present. This is case insensitive and should be used rather than looking up h verbatim in headers.

val get_header_int : _ t -> string -> int option

Same as get_header but also performs a string to integer conversion.

val set_header : string -> string -> 'a t -> 'a t

set_header k v req sets k: v in the request req's headers.

val remove_header : string -> 'a t -> 'a t

Remove one instance of this header.

  • since 0.17
val update_headers : (Headers.t -> Headers.t) -> 'a t -> 'a t

Modify headers using the given function.

  • since 0.11
val set_body : 'a -> _ t -> 'a t

set_body b req returns a new query whose body is b.

  • since 0.11
val host : _ t -> string

Host field of the request. It also appears in the headers.

val client_addr : _ t -> Unix.sockaddr

Client address of the request.

  • since 0.16
val meth : _ t -> Meth.t

Method for the request.

val path : _ t -> string

Request path.

val query : _ t -> (string * string) list

Decode the query part of the path field.

  • since 0.4
val body : 'b t -> 'b

Request body, possibly empty.

val start_time : _ t -> float

time stamp (from Unix.gettimeofday) after parsing the first line of the request

  • since 0.11
val limit_body_size : max_size:int -> bytes:bytes -> IO.Input.t t -> diff --git a/tiny_httpd/Tiny_httpd_core/Server/module-type-IO_BACKEND/index.html b/tiny_httpd/Tiny_httpd_core/Server/module-type-IO_BACKEND/index.html index f0465968..7c00c44c 100644 --- a/tiny_httpd/Tiny_httpd_core/Server/module-type-IO_BACKEND/index.html +++ b/tiny_httpd/Tiny_httpd_core/Server/module-type-IO_BACKEND/index.html @@ -1,2 +1,2 @@ -IO_BACKEND (tiny_httpd.Tiny_httpd_core.Server.IO_BACKEND)

Module type Server.IO_BACKEND

A backend that provides IO operations, network operations, etc.

This is used to decouple tiny_httpd from the scheduler/IO library used to actually open a TCP server and talk to clients. The classic way is based on Unix and blocking IOs, but it's also possible to use an OCaml 5 library using effects and non blocking IOs.

val init_addr : unit -> string

Initial TCP address

val init_port : unit -> int

Initial port

val get_time_s : unit -> float

Obtain the current timestamp in seconds.

val tcp_server : unit -> IO.TCP_server.builder

TCP server builder, to create servers that can listen on a port and handle clients.

+IO_BACKEND (tiny_httpd.Tiny_httpd_core.Server.IO_BACKEND)

Module type Server.IO_BACKEND

A backend that provides IO operations, network operations, etc.

This is used to decouple tiny_httpd from the scheduler/IO library used to actually open a TCP server and talk to clients. The classic way is based on Unix and blocking IOs, but it's also possible to use an OCaml 5 library using effects and non blocking IOs.

val init_addr : unit -> string

Initial TCP address

val init_port : unit -> int

Initial port

val get_time_s : unit -> float

Obtain the current timestamp in seconds.

val tcp_server : unit -> IO.TCP_server.builder

TCP server builder, to create servers that can listen on a port and handle clients.

diff --git a/tiny_httpd/Tiny_httpd_core/Server/module-type-UPGRADE_HANDLER/index.html b/tiny_httpd/Tiny_httpd_core/Server/module-type-UPGRADE_HANDLER/index.html index c18828ba..03cb289d 100644 --- a/tiny_httpd/Tiny_httpd_core/Server/module-type-UPGRADE_HANDLER/index.html +++ b/tiny_httpd/Tiny_httpd_core/Server/module-type-UPGRADE_HANDLER/index.html @@ -1,5 +1,5 @@ UPGRADE_HANDLER (tiny_httpd.Tiny_httpd_core.Server.UPGRADE_HANDLER)

Module type Server.UPGRADE_HANDLER

Handler that upgrades to another protocol.

  • since 0.17
type handshake_state

Some specific state returned after handshake

val name : string

Name in the "upgrade" header

val handshake : - Unix.sockaddr -> + Unix.sockaddr -> unit Request.t -> (Headers.t * handshake_state, string) result

Perform the handshake and upgrade the connection. This returns either Ok (resp_headers, state) in case of success, in which case the server sends a 101 response with resp_headers; or it returns Error log_msg if the the handshake fails, in which case the connection is closed without further ado and log_msg is logged locally (but not returned to the client).

val handle_connection : handshake_state -> IO.Input.t -> IO.Output.t -> unit

Take control of the connection and take it from ther.e

diff --git a/tiny_httpd/Tiny_httpd_core/Util/index.html b/tiny_httpd/Tiny_httpd_core/Util/index.html index cf3c796b..833b72b3 100644 --- a/tiny_httpd/Tiny_httpd_core/Util/index.html +++ b/tiny_httpd/Tiny_httpd_core/Util/index.html @@ -1,2 +1,2 @@ -Util (tiny_httpd.Tiny_httpd_core.Util)

Module Tiny_httpd_core.Util

Some utils for writing web servers

  • since 0.2
val percent_encode : ?skip:(char -> bool) -> string -> string

Encode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1

  • parameter skip

    if provided, allows to preserve some characters, e.g. '/' in a path.

val percent_decode : string -> string option

Inverse operation of percent_encode. Can fail since some strings are not valid percent encodings.

val split_query : string -> string * string

Split a path between the path and the query

  • since 0.5
val split_on_slash : string -> string list

Split a string on '/', remove the trailing '/' if any.

  • since 0.6
val get_non_query_path : string -> string

get the part of the path that is not the query parameters.

  • since 0.5
val get_query : string -> string

Obtain the query part of a path.

  • since 0.4
val parse_query : string -> ((string * string) list, string) result

Parse a query as a list of '&' or ';' separated key=value pairs. The order might not be preserved.

  • since 0.3
val show_sockaddr : Unix.sockaddr -> string

Simple printer for socket addresses.

  • since 0.17
val is_ipv6_str : string -> bool

Is this string potentially an IPV6 address?

  • since 0.17
+Util (tiny_httpd.Tiny_httpd_core.Util)

Module Tiny_httpd_core.Util

Some utils for writing web servers

  • since 0.2
val percent_encode : ?skip:(char -> bool) -> string -> string

Encode the string into a valid path following https://tools.ietf.org/html/rfc3986#section-2.1

  • parameter skip

    if provided, allows to preserve some characters, e.g. '/' in a path.

val percent_decode : string -> string option

Inverse operation of percent_encode. Can fail since some strings are not valid percent encodings.

val split_query : string -> string * string

Split a path between the path and the query

  • since 0.5
val split_on_slash : string -> string list

Split a string on '/', remove the trailing '/' if any.

  • since 0.6
val get_non_query_path : string -> string

get the part of the path that is not the query parameters.

  • since 0.5
val get_query : string -> string

Obtain the query part of a path.

  • since 0.4
val parse_query : string -> ((string * string) list, string) result

Parse a query as a list of '&' or ';' separated key=value pairs. The order might not be preserved.

  • since 0.3
val show_sockaddr : Unix.sockaddr -> string

Simple printer for socket addresses.

  • since 0.17
val is_ipv6_str : string -> bool

Is this string potentially an IPV6 address?

  • since 0.17
diff --git a/tiny_httpd/Tiny_httpd_unix/Unix_tcp_server_/index.html b/tiny_httpd/Tiny_httpd_unix/Unix_tcp_server_/index.html index 06acaaab..47707de8 100644 --- a/tiny_httpd/Tiny_httpd_unix/Unix_tcp_server_/index.html +++ b/tiny_httpd/Tiny_httpd_unix/Unix_tcp_server_/index.html @@ -1,2 +1,2 @@ -Unix_tcp_server_ (tiny_httpd.Tiny_httpd_unix.Unix_tcp_server_)

Module Tiny_httpd_unix.Unix_tcp_server_

val get_addr_ : Unix.file_descr -> Unix.inet_addr * int
type t = {
  1. addr : string;
  2. port : int;
  3. buf_pool : Tiny_httpd_core.Buf.t Tiny_httpd_core.Pool.t;
  4. slice_pool : Tiny_httpd_core.IO.Slice.t Tiny_httpd_core.Pool.t;
  5. max_connections : int;
  6. sem_max_connections : Sem.t;
    (*

    semaphore to restrict the number of active concurrent connections

    *)
  7. mutable sock : Unix.file_descr option;
    (*

    Socket

    *)
  8. new_thread : (unit -> unit) -> unit;
  9. timeout : float;
  10. masksigpipe : bool;
  11. mutable running : bool;
}
val shutdown_silent_ : Unix.file_descr -> unit
val close_silent_ : Unix.file_descr -> unit
+Unix_tcp_server_ (tiny_httpd.Tiny_httpd_unix.Unix_tcp_server_)

Module Tiny_httpd_unix.Unix_tcp_server_

val get_addr_ : Unix.file_descr -> Unix.inet_addr * int
type t = {
  1. addr : string;
  2. port : int;
  3. buf_pool : Tiny_httpd_core.Buf.t Tiny_httpd_core.Pool.t;
  4. slice_pool : Tiny_httpd_core.IO.Slice.t Tiny_httpd_core.Pool.t;
  5. max_connections : int;
  6. sem_max_connections : Sem.t;
    (*

    semaphore to restrict the number of active concurrent connections

    *)
  7. mutable sock : Unix.file_descr option;
    (*

    Socket

    *)
  8. new_thread : (unit -> unit) -> unit;
  9. timeout : float;
  10. masksigpipe : bool;
  11. mutable running : bool;
}
val shutdown_silent_ : Unix.file_descr -> unit
val close_silent_ : Unix.file_descr -> unit
diff --git a/tiny_httpd/_doc-dir/CHANGES.md b/tiny_httpd/_doc-dir/CHANGES.md index 5ab4a144..5561af63 100644 --- a/tiny_httpd/_doc-dir/CHANGES.md +++ b/tiny_httpd/_doc-dir/CHANGES.md @@ -1,4 +1,23 @@ +## 0.19 + +- feat(headers): `set` will not reallocate whole list if not needed +- feat(headers): use case insensitive comparison +- fix(response): do not override "content-length" in raw response +- feat pool: expose `acquire/release` for advanced uses + +## 0.18 + +- feat: add ?head_middlewares to `create` +- add content-type header for prometheus endpoint +- new flag ?enable_logging to disable regular logs (not debug) +- new sublibrary to deal with multipart-form-data +- feat response: add `pp_with`; have `pp` hide set-cookie headers + +- fix percent encoding for < 0x10 chars +- Processing to fix incompatible -O and gcc flags +- fix: make check for 'Connection: Upgrade' header case-insensitive + ## 0.17 - add optional middlewares to tiny_httpd_ws diff --git a/tiny_httpd_camlzip/_doc-dir/CHANGES.md b/tiny_httpd_camlzip/_doc-dir/CHANGES.md index 5ab4a144..5561af63 100644 --- a/tiny_httpd_camlzip/_doc-dir/CHANGES.md +++ b/tiny_httpd_camlzip/_doc-dir/CHANGES.md @@ -1,4 +1,23 @@ +## 0.19 + +- feat(headers): `set` will not reallocate whole list if not needed +- feat(headers): use case insensitive comparison +- fix(response): do not override "content-length" in raw response +- feat pool: expose `acquire/release` for advanced uses + +## 0.18 + +- feat: add ?head_middlewares to `create` +- add content-type header for prometheus endpoint +- new flag ?enable_logging to disable regular logs (not debug) +- new sublibrary to deal with multipart-form-data +- feat response: add `pp_with`; have `pp` hide set-cookie headers + +- fix percent encoding for < 0x10 chars +- Processing to fix incompatible -O and gcc flags +- fix: make check for 'Connection: Upgrade' header case-insensitive + ## 0.17 - add optional middlewares to tiny_httpd_ws