module Netsys:sig..end
Unix modulefd_style indicates which I/O function to call. Sometimes it is
    mandatory to call this function, sometimes it is only a good advice
    because the function provides the best interface for the kind of
    descriptor.typefd_style =[ `Read_write
| `Recv_send of Unix.sockaddr * Unix.sockaddr
| `Recv_send_implied
| `Recvfrom_sendto
| `W32_event
| `W32_input_thread
| `W32_output_thread
| `W32_pipe
| `W32_pipe_server
| `W32_process ]
`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. 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.val get_fd_style : Unix.file_descr -> fd_styleval gread : fd_style -> Unix.file_descr -> string -> int -> int -> intgread 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.
val blocking_gread : fd_style -> Unix.file_descr -> string -> int -> int -> intlet 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.
val really_gread : fd_style -> Unix.file_descr -> string -> int -> int -> unitreally_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.
val gwrite : fd_style -> Unix.file_descr -> string -> int -> int -> intgwrite 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.val really_gwrite : fd_style -> Unix.file_descr -> string -> int -> int -> unitreally_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.
exception Shutdown_not_supported
gshutdownval gshutdown : fd_style -> Unix.file_descr -> Unix.shutdown_command -> unitgshutdown 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.Shutdown_not_supported.val is_readable : fd_style -> Unix.file_descr -> boolval is_writable : fd_style -> Unix.file_descr -> boolval is_prird : fd_style -> Unix.file_descr -> bool
      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.)
      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.
val wait_until_readable : fd_style -> Unix.file_descr -> float -> boolval wait_until_writable : fd_style -> Unix.file_descr -> float -> boolval wait_until_prird : fd_style -> Unix.file_descr -> float -> booltrue). 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.)
      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.
val gclose : fd_style -> Unix.file_descr -> unit
      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).
val wait_until_connected : Unix.file_descr -> float -> boolfloat 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.
val connect_check : Unix.file_descr -> unitUnix.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.
val domain_of_inet_addr : Unix.inet_addr -> Unix.socket_domainval protostring_of_inet_addr : Unix.inet_addr -> stringval inet_addr_of_protostring : string -> Unix.inet_addrval getpeername : Unix.file_descr -> Unix.sockaddrUnix.getpeername, but errors are fixed up. ENOTCONN is
      ensured when the socked is unconnected or shut down.val is_absolute : string -> boolval restart : ('a -> 'b) -> 'a -> 'brestart 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:
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 POSIXval restart_tmo : (float -> 'b) -> float -> 'brestart_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".
val restarting_select : Unix.file_descr list ->
       Unix.file_descr list ->
       Unix.file_descr list ->
       float -> Unix.file_descr list * Unix.file_descr list * Unix.file_descr listUnix.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.
val sleep : float -> unitval restarting_sleep : float -> unitrestarting_sleep additionally handles
      EINTR.val unix_error_of_code : int -> Unix.errorval int64_of_file_descr : Unix.file_descr -> int64val string_of_fd : Unix.file_descr -> stringval string_of_sockaddr : Unix.sockaddr -> string
      Note that the reverse (parsing such a string) can be
      accomplished with Netsockaddr.socksymbol_of_string and
      Uq_resolver.sockaddr_of_socksymbol.
val string_of_fd_style : fd_style -> stringval is_stdin : Unix.file_descr -> boolval is_stdout : Unix.file_descr -> boolval is_stderr : Unix.file_descr -> boolval set_close_on_exec : Unix.file_descr -> unitval clear_close_on_exec : Unix.file_descr -> unitUnixval _exit : int -> unitexit.val logand_inet_addr : Unix.inet_addr -> Unix.inet_addr -> Unix.inet_addrval logor_inet_addr : Unix.inet_addr -> Unix.inet_addr -> Unix.inet_addrval logxor_inet_addr : Unix.inet_addr -> Unix.inet_addr -> Unix.inet_addrval lognot_inet_addr : Unix.inet_addr -> Unix.inet_addrval is_ipv4_inet_addr : Unix.inet_addr -> boolval is_ipv6_inet_addr : Unix.inet_addr -> boolval is_multicast_inet_addr : Unix.inet_addr -> boolval mcast_set_loop : Unix.file_descr -> bool -> unitval mcast_set_ttl : Unix.file_descr -> int -> unitval mcast_add_membership : Unix.file_descr -> Unix.inet_addr -> Unix.inet_addr -> unit
      First inet addr is the group to join. Second inet addr selects the
      network interface (or Unix.inet_addr_any).
val mcast_drop_membership : Unix.file_descr -> Unix.inet_addr -> Unix.inet_addr -> unit
     First inet addr is the group to leave. Second inet addr selects the
     network interface (or Unix.inet_addr_any).
val moncontrol : bool -> unitmoncontrol 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.
val blocking_read : Unix.file_descr -> string -> int -> int -> intblocking_gread `Read_writeval really_read : Unix.file_descr -> string -> int -> int -> unitreally_gread `Read_writeval really_write : Unix.file_descr -> string -> int -> int -> unitreally_gwrite `Read_writeNetsys_posix.typeshm_open_flag =Netsys_posix.shm_open_flag=
| | | SHM_O_RDONLY | 
| | | SHM_O_RDWR | 
| | | SHM_O_CREAT | 
| | | SHM_O_EXCL | 
| | | SHM_O_TRUNC | 
val have_posix_shm : unit -> boolval shm_open : string -> shm_open_flag list -> int -> Unix.file_descrval shm_unlink : string -> unit
    After reading from uni-directional descriptors, and seeing the
    EOF, it is usually sufficient to call gclose to free OS resources.
    After writing to uni-directional descriptors one should call
    gshutdown to send an EOF (SHUTDOWN_SEND). For some descriptors
    one will get the exception Shutdown_not_supported which can be
    ignored in this context The gshutdown function cannot,
    however, report in all cases whether the operation was successful.
    As a rule of thumb, error reporting works for local data connections,
    but not always for remote connections, and there is no way to fix
    this. After writing EOF, call gclose to free OS resources.
For bidirectional connections, it is even more complicated. If the connection is local, a bidirectional connection behaves much like a pair of unidirectional connections. However, in the network case, we have to go down to the protocol level.
For TCP the golden rule is that the client initiates the connection, and the client finishes the connection. The case that the server finishes the connection is not well-specified - or better, the server needs the ACK from the client after triggering the connection termination. In practice we have the cases:
gshutdown with SHUTDOWN_SEND and then waits until the EOF from 
      the server arrives,
      and then gcloses the descriptor. It may happen that the client
      gets an error if some problem occurs, so this is reliable from the
      perspective of the client. The server first sees the EOF from the
      client, and then responds with another gshutdown, followed by 
      gclose. From the server's perspective it does not matter whether
      the operation results in an error or not - the client has lost
      interest anyway.gshutdown. There
      is no way to fix this. (One should better fix the application protocol. 
      Note
      that even prominent researchers trapped into this problem. For example,
      the first version of HTTP had this problem.)gshutdown
      it is forbidden to immediately gclose, because this may result
      in a connection reset. Instead, the server has to wait for the 
      client's EOF. (This is called "lingering".) If the client's EOF is
      seen one can gclose.module Debug:sig..end