Module Netsys

Some information what kind of operations are reasonable for descriptors:

• `Read_write: The descriptor is neither a socket not one of the other special cases, so only read/write is possible if read/write is possible at all. This style is also used if it is meaningless to use data I/O like read/write at all.
• `Recv_send(sockaddr,peeraddr): The descriptor is a connected socket. recv/send are the preferred operations.
• `Recvfrom_sendto: The descriptor is an unconnected socket, and it is possible to ask for addresses when exchanging data, so recvfrom/sendto are the preferred operations.
• `Recv_send_implied: The descriptor is a socket with implied connection. There are no socket addresses. recv/send are the preferred operations. It is not possible to call getsockname or getpeername.
• `W32_pipe: The descriptor is a proxy descriptor for a Win32 named pipe as returned by Netsys_win32.pipe_descr.
• `W32_pipe_server: The descriptor is a proxy descriptor for a Win32 pipe server as returned by Netsys_win32.pipe_server_descr.
• `W32_event: The descriptor is a Win32 proxy descriptor for an event as returned by Netsys_win32.create_event. It is not possible to read/write with these descriptors.
• `W32_process: The descriptor is a proxy descriptor for a Win32 process as returned by Netsys_win32.create_process. It is not possible to read/write with these descriptors.
• `W32_input_thread: The descriptor is a proxy descriptor for a Win32-specific input thread as returned by Netsys_win32.create_input_thread.
• `W32_output_thread: The descriptor is a proxy descriptor for a Win32-specific output thread as returned by Netsys_win32.create_output_thread.
• `TLS endpoint: A TLS tunnel is running over the descriptor. The details of the tunnel can be found in endpoint. Note that it is allowed that the endpoint uses a second descriptor for either reading or writing (i.e. reading and writing go via different descriptors). In this case, it is sufficient that one of these descriptors is accompanied with `TLS endpoint.

Win32: For the exact meaning of proxy descriptors, please see Netsys_win32. In short, a proxy descriptor is an abstract handle for the I/O object. The handle itself cannot be used for I/O, however, but only some specialized function. The proxy descriptor can only be used to dereference the I/O object. Note that the following functions like gread and gwrite automatically look up the I/O object behind the proxy and call the right I/O function.

Get the file descriptor style.

The following styles cannot be determined automatically:

• `TLS

gread fd_style fd s pos len: Reads up to len bytes from descriptor fd which is supposed to support the I/O style fd_style, i.e. the right system call (read, recv, recvfrom) is chosen to read from the descriptor. After n <= len bytes have been read these are put into string s at positions pos to pos+n-1, and n is returned. The function can fail with any I/O exception defined for the actually performed I/O operation. Whether the operation is blocking or non-blocking depends on the descriptor.

If len>0 but n=0 the end of the input data is reached.

Same for a tagged buffer

let p = blocking_gread fd_style fd s pos len: Like gread up to len bytes are read from fd and stored in s. If the I/O operation is blocking but the descriptor is in non-blocking mode, this function blocks until the operation can be performed. If the operation is interrupted by a signal it is automatically restarted.

If n < len the end of the input data is reached (where n is the returned number).

See wait_until_readable below for further information which types of descriptors can be handled in non-blocking mode.

Same for a tagged buffer

really_read fd_style fd s pos len: Reads exactly len bytes from fd and stores them in s starting at pos. If the end of file condition is seen before len bytes are read, the exception End_of_file is raised, and it is unspecified how many bytes have been stored in s. Like blocking_gread, non-blocking descriptors are forced to block until the operation becomes possible, and interruptions by signals are handled.

See wait_until_readable below for further information which types of descriptors can be handled in non-blocking mode.

Same for a tagged buffer

gwrite fd_style fd s pos len: Writes up to len bytes to descriptor fd which is supposed to support the I/O style fd_style, i.e. the right system call (write, send, sendto) is chosen to write to the descriptor. . The n <= len written bytes are taken from string s, starting at position pos until pos+n-1. The number n is returned. The function can fail with any I/O exception defined for the actually performed I/O operation. Whether the operation is blocking or non-blocking depends on the descriptor.

Same for a tagged string

Same for a tagged buffer

really_write fd_style fd s pos len: Writes exactly the len bytes from s to fd starting at pos. If the I/O operation is blocking but the descriptor is in non-blocking mode, this function blocks until the operation can be performed. If the operation is interrupted by a signal it is automatically restarted.

See wait_until_writable below for further information which types of descriptors can be handled in non-blocking mode.

Same for a tagged string

Same for a tagged buffer

See gshutdown

gshutdown fd_style fd cmd: If there is the possibility to shut down the connection for this kind of descriptor, the shutdown is tried. It is possible that the function raises the EAGAIN Unix error if the shutdown operation is non-blocking, and currently not possible. It is suggested to wait until the descriptor is writable, and to try again then.

If there is no shutdown operation for this kind of descriptor, the exception Shutdown_not_supported is raised. In this case it is usually sufficient to close the descriptor (gclose, see below), and when all descriptors to the resource are closed, the resource is shut down by the OS.

Details by fd_style:

• `Recv_send and `Recv_send_implied: The socket is shut down as requested by Unix.shutdown. This only triggers the shutdown, but does not wait until it is completed. Also, errors are usually not immediately reported.
• `W32_pipe: It is only possible to request SHUTDOWN_ALL for these descriptors. For other shutdown types, the error EPERM is reported. The shutdown is synchronous and completed when the function returns.
• `W32_pipe_server: It is only possible to request SHUTDOWN_ALL for these descriptors. For other shutdown types, the error EPERM is reported. A shutdown means here to stop accepting new connections. The shutdown is synchronous and completed when the function returns.
• `W32_output_thread: It is only possible to request SHUTDOWN_SEND for these descriptors. A SHUTDOWN_ALL is also interpreted as SHUTDOWN_SEND, and a SHUTDOWN_RECEIVE is ignored. A shutdown means here that the EOF is appended to the output buffer, and when the output thread has written the buffer contents, the underlying descriptor (not fd!) will be closed. The shutdown operation is non-blocking. If it is not possible at the moment of calling, the error EAGAIN is reported.
• `TLS: The shutdown only affects the tunnel as such, but not the underlying connection. SHUTDOWN_SEND and SHUTDOWN_ALL are supported. SHUTDOWN_RECEIVE is ignored.
• Other styles raise Shutdown_not_supported.

Test whether the descriptor would not block if one of the input, output, or priority input operations were done.

On POSIX systems the tests work for a wide variety of descriptor types (but not for regular files which are assumed to be always readable and writable). If the poll interface is available it is preferred over the select interface to conduct the test.

On Win32, the tests are limited to sockets, named pipes and event objects. (The latter two only in the form provided by Netsys_win32, see there.)

For `TLS fd styles, the functions are "best effort" only.

Generally, if the blocking status cannot be determined for a class of I/O operations, the functions return true, in the hope that it is better to block than to never conduct the operation.

Wait until an operation for a single descriptor becomes possible. The float argument is the timeout (negative value means no timeout). Returns whether the operation is possible (true). Otherwise, there was a timeout (false).

On POSIX systems this works for a wide variety of descriptor types (but not for regular files which are assumed to be always readable and writable). If the poll interface is available it is preferred over the select interface to wait for I/O. The functions also catch interruptions by signals.

On Win32, waiting is limited to sockets, named pipes and event objects. (The latter two only in the form provided by Netsys_win32, see there.)

For `TLS fd styles, the functions are "best effort" only.

Generally, if waiting is not supported for a class of I/O operations, the functions return immediately true, in the hope that it is better to block than to never conduct the operation.

Shuts down the system object referenced by the descriptor so far possible, and closes the descriptor.

Errors are logged to Netlog as `Crit events, and do not generate exceptions.

The exact semantics of the close operation varies from descriptor style to descriptor style. Generally, gclose assumes that all I/O is done, and all buffers are flushed, and that one can tear down the underlying communication circuits. gclose is always the right choice when the I/O channel needs to be aborted after a fatal error, and it does not matter whether errors occur or not. If a data connection needs to be orderly closed (i.e. without data loss), one should first try to finish the communication, either by protocol means (e.g. wait for ACK messages), or by calling gshutdown first (see above).

After a non-blocking connect has been initiated, this function can be used to wait until (1) the connect is successful, or (2) the connect fails, or (3) the operation times out. The float argument is the timeout value (negative value means no timeout). The function returns true for the cases (1) and (2), and false for case (3). The cases (1) and (2) can be further analyzed by calling connect_check (see below).

On POSIX, this function is identical to wait_until_writable. On Win32 the wait condition is slightly different.

On Win32, this function also tolerates client proxy descriptors for Win32 named pipes. However, there is no waiting - the function immediately returns.

Tests whether the socket is connected with the peer after calling Unix.connect. If the socket is connected, the function returns normally. Otherwise, the current socket error is raised as a Unix.Unix_error exception. This function is intended to be called after a non-blocking connect has been initiated, and the success or error is indicated (e.g. after wait_until_connected returns).

Side effect: The per-socket error code may be reset.

On Win32, this function also tolerates client proxy descriptors for Win32 named pipes. However, there is no real check - the function immediately returns.

Returns the socket domain of Internet addresses, i.e. whether the address is IPv4 or IPv6

Converts an IP address to the 4 bytes (IPv4) or 16 bytes (IPv6) representation in network byte order, and vice-versa

like Unix.getpeername, but errors are fixed up. ENOTCONN is ensured when the socked is unconnected or shut down.

Whether this file path is absolute. Works for Unix and Win32.

Return an absolute path for this file. When Netsys_posix.realpath is available, this function is called, and the canonical path is returned. On Win32, first an arbitrary absolute path is created, and then the path is tried to be simplified by resolving "." and "..". If neither method works, the function raises Invalid_argument.

Note that the file needs to exist in general.

restart f arg calls f arg, and restarts this call if the exception Unix_error(EINTR,_,_) is caught.

Note that there are some cases where this handling of EINTR is not sufficient:

• Functions that have a timeout argument like Unix.select: When EINTR is caught the timeout should be adjusted.
• Unix.connect with a blocking descriptor because this is not well-enough specified by POSIX

restart_tmo f tmo calls f with a timeout argument tmo, and restarted the call if the exception Unix_error(EINTR,_,_) is caught. In the restart case, the timeout argument is reduced by the already elapsed time.

Negative timeout arguments are interpreted as "no timeout".

A wrapper around Unix.select that handles the EINTR condition.

Note: This function calls Unix.select and shares all pros and cons with Unix.select. In particular, the OS often sets a limit on the number (and/or the numeric value) of the descriptors (e.g. for Linux it is 1024, for Windows it is 64). On Ocaml 3.11 the Windows version of Unix.select includes some support for other types of descriptors than sockets.

restart_wait mode fd_style fd f arg: Calls f arg, and handles the following exceptions:

• Unix_error(EINTR,_,_): Just calls f again
• Unix_error(EAGAIN,_,_): waits until fd is readable or writable as designated by mode, and calls f again
• Unix_error(EWOUDLBLOCK,_,_): same
• Netsys_types.EAGAIN_RD: waits until fd is readable, and calls f again
• Netsys_types.EAGAIN_WR: waits until fd is writable, and calls f again

Sleep for the passed time. restarting_sleep additionally handles EINTR.

Converts an integer error into the corresponding variant

Returns the file descriptor as int64 number. Works for all OS.

Return a string describing the descriptor (for debugging)

Returns a human-readable string describing the address (for debug messages). If norm, IPv4 addresses mapped to the IPv6 address space are returned in the normal dotted quad format (i.e. x.y.z.u instead of ::ffff:x.y.z.u).

Note that the reverse (parsing such a string) can be accomplished with Netsockaddr.socksymbol_of_string and Uq_resolver.sockaddr_of_socksymbol.

Returns a string describing the fd style (debugging)

Returns whether the descriptors are stdin/stdout/stderr

Working versions of the functions with the same name in Unix

Exit the program immediately without running the atexit handlers. The argument is the exit code, just as for exit.

Whether IPv6 is available and usable. At the moment this tests for the presence of a global IPv6 address on any interface. The test also requires that the getifaddrs() call is available. The test can be overridden with set_ipv6_system.

Sets whether IPv6 is usable

Returns the bitwise AND of the two argument addresses

Returns the bitwise OR of the two argument addresses

Returns the bitwise XOR of the two argument addresses

Returns the bitwise NOT of the argument address

Normalization: If the input address is an IPv4 address mapped into the IPv6 address space, the IPv4 address is extracted. Otherwise, the input address is returned unchanged.

IPv6-ification: If the input address is for IPv4, it is mapped to the IPv6 address space (so an IPv6 socket can be bound)

Whether the address is an IPv4 address (including IPv4 addresses mapped into the IPv6 adress space)

Whether the address is an IPv6 address (excluding IPv4 addresses mapped into the IPv6 adress space)

Whether the address is a multicast address (either IPv4 or IPv6)

Whether sent multicast messages are received by the sending host

Set TTL/hops value

Join a multicast group.

First inet addr is the group to join. Second inet addr selects the network interface (or Unix.inet_addr_any).

Leave a multicast group.

First inet addr is the group to leave. Second inet addr selects the network interface (or Unix.inet_addr_any).

Interface to the moncontrol routine of the GPROF profiler. moncontrol false stops profiling; moncontrol true starts profiling again.

This is a no-op if the program is not compiler for profiling.