module Netsys_win32:sig
..end
type
w32_event
val create_event : unit -> w32_event
val set_event : w32_event -> unit
val reset_event : w32_event -> unit
val test_event : w32_event -> bool
val event_wait : w32_event -> float -> bool
val event_descr : w32_event -> Unix.file_descr
lookup
below for
more on proxy descriptors. This function always returns the same
descriptor. The user has to close this descriptor if this function
is called.val wsa_event_select : w32_event ->
Unix.file_descr -> Netsys_posix.poll_req_events -> unit
val wsa_maximum_wait_events : unit -> int
wsa_wait_for_multiple_events
val wsa_wait_for_multiple_events : w32_event array -> int -> int option
The function returns the first index in the array that is signaled.
On timeout, None
is returned.
The return value WSA_WAIT_IO_COMPLETION
is mapped to the
Unix error EINTR
.
val wsa_enum_network_events : Unix.file_descr -> w32_event -> Netsys_posix.poll_act_events
val real_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 list
Unix.select
. In
3.11, the latter was changed to a smart implementation that promises
to handle other types of handles in addition to sockets. As we do
the same in Netsys
, this would be a duplication of work. Also,
the older implementation is more mature.listen
and accept
). There is a
w32_pipe_server
representing pipe servers. An individual pipe
is wrapped into a w32_pipe
.
Win32 named pipes do not allow to check whether an operation would block before starting the operation. There is so-called overlapped I/O, but it works differently than Unix-style multiplexing.
The following functions add a layer to the Win32 primitives that
helps using pipes in a way similar to multiplexing. We allocate
buffers for input and output, and the functions pipe_read
and
pipe_write
access these buffers in the first place. When reading,
but the read buffer is empty, we start an overlapped read operation
from the pipe handle. The arriving data refills the read buffer, and
a w32_event
is signaled to wake up any pending event loop.
During the pending read from the pipe handle, the read buffer is
locked, and pipe_read
will return EWOULDBLOCK
.
Writing is slightly more difficult. The first pipe_write
puts
the data into the write buffer, and immediately starts an overlapped
I/O operation to write the data to the pipe handle. During this
operation the write buffer is locked, and cannot be further used
to accumulate data, even if there is space. So pipe_write
will
return EWOULDBLOCK
while the operation takes place. A w32_event
is
signaled when the write operation is over.
The only downside of this approach is that the caller has to use
pipe_read
and pipe_write
to access pipes, instead of
Unix.read
and Unix.write
. If generic r/w functions are
required that work for numerous kinds of descriptors, there are
Netsys.gread
and Netsys.gwrite
which support named
pipes.
type
w32_pipe_server
w32_pipe_server
contains the server endpoints of
a number of pipes, and a few helper objects.type
w32_pipe
type
pipe_mode =
| |
Pipe_in |
| |
Pipe_out |
| |
Pipe_duplex |
val rev_mode : pipe_mode -> pipe_mode
val create_local_pipe_server : string -> pipe_mode -> int -> w32_pipe_server
create_local_named_pipe name mode n
: Create a pipe server.
The name
must have the format "\\.\pipe\<name>".
In n
the maximum number of instances is passed. The server is
set up with a security descriptor so only clients on the same system
can connect.val pipe_listen : w32_pipe_server -> int -> unit
n
prepared server endpoints.
One can check for new client connections by looking at the
pipe_connect_event
.
val pipe_accept : w32_pipe_server -> w32_pipe
val pipe_connect : string -> pipe_mode -> w32_pipe
pipe_connect name mode
: Creates a client pipe handle, and tries
to connect to the pipe server name
. The function fails with the
Unix error EAGAIN
if there are currently no listening instances of the
pipe at the server.
The name must be of the form "\\.\pipe\<name>" (excluding connects to pipes on remote systems). This function allows only connects to local pipe servers, and enforces anonymous impersonation.
Note that you also can connect to named pipes using open_in
and
Unix.openfile
, and that these functions do not protect against
malicious servers that impersonate as the caller.
val pipe_pair : pipe_mode -> w32_pipe * w32_pipe
pipe_mode
, and the
right pipe is in the matching complementaty mode.val pipe_read : w32_pipe -> string -> int -> int -> int
pipe_read p s pos len
: Tries to read data from the pipe. If data
is available, it is put into the len
bytes at position pos
of
the string s
, and the actual number of read bytes is returned.
If no data is available, the function fails with a Unix error of
EAGAIN
.
If the end of the pipe is reached, the function returns 0.
val pipe_write : w32_pipe -> string -> int -> int -> int
pipe_write p s pos len
: Tries to write data to the pipe. If space
is available, the data is taken from the len
bytes at position pos
of
the string s
, and the actual number of written bytes is returned.
If no space is available, the function fails with a Unix error of
EAGAIN
.
val pipe_shutdown : w32_pipe -> unit
Note that there is no way to close only one direction of bidirectional pipes.
See the comments on closing pipes below.
val pipe_shutdown_server : w32_pipe_server -> unit
pipe_accept
ed, it is simply destroyed by this function.val pipe_connect_event : w32_pipe_server -> w32_event
val pipe_rd_event : w32_pipe -> w32_event
val pipe_wr_event : w32_pipe -> w32_event
val pipe_wait_connect : w32_pipe_server -> float -> bool
val pipe_wait_rd : w32_pipe -> float -> bool
val pipe_wait_wr : w32_pipe -> float -> bool
val pipe_server_descr : w32_pipe_server -> Unix.file_descr
lookup
below for
more on proxy descriptors. This function always returns the same
descriptor. The user has to close this descriptor if this function
is called.val pipe_descr : w32_pipe -> Unix.file_descr
lookup
below for
more on proxy descriptors. This function always returns the same
descriptor. The user has to close this descriptor if this function
is called.val pipe_name : w32_pipe -> string
val pipe_server_name : w32_pipe_server -> string
val pipe_mode : w32_pipe -> pipe_mode
val pipe_server_mode : w32_pipe_server -> pipe_mode
val unpredictable_pipe_name : unit -> string
pipe_shutdown
. The server then sees EOF when reading from the pipe,
or gets an EPIPE
error when writing to the pipe. The server should
then also pipe_shutdown
the endpoint.
When servers start the closure of connections, there is no clean way
of ensuring that all written data are transmitted. There is the
FlushFileBuffers
Win32 function, but it is blocking.
I/O threads are only available if the application is compiled as
multi-threaded program.
type
w32_input_thread
val create_input_thread : Unix.file_descr -> w32_input_thread
input_thread_read
.
The thread continues to run until EOF is reached, an I/O error
occurs, or until the
thread is cancelled (cancel_input_thread
).
After starting the input thread, the file descriptor must not
be used anymore. It is now owned by the input thread.
val input_thread_event : w32_input_thread -> w32_event
val input_thread_read : w32_input_thread -> string -> int -> int -> int
input_thread_read t s pos len
: Tries to read data from the buffer.
If data
is available, it is put into the len
bytes at position pos
of
the string s
, and the actual number of read bytes is returned.
If no data is available, the function fails with a Unix error of
EAGAIN
(non-blocking).
If the end of the data is reached, the function returns 0.
For cancelled requests, the function raises EPERM
.
val cancel_input_thread : w32_input_thread -> unit
The thread is automatically cancelled by the GC finaliser. However,
users are encouraged to call cancel_input_thread
as soon as
the thread is no longer needed, because a thread is an expensive
resource.
Implementation note: Actually, cancellation is only fully implemented
on Windows Vista. On XP the actual cancellation may be delayed
indefinetely.
val input_thread_proxy_descr : w32_input_thread -> Unix.file_descr
type
w32_output_thread
val create_output_thread : Unix.file_descr -> w32_output_thread
output_thread_read
.
The thread continues to run until it is explicitly closed, or
an I/O error occurs, or until the
thread is cancelled (cancel_output_thread
).
After starting the output thread, the file descriptor must not
be used anymore. It is now owned by the output thread.
val output_thread_event : w32_output_thread -> w32_event
val output_thread_write : w32_output_thread -> string -> int -> int -> int
output_thread_write t s pos len
: Tries to write data to the buffer.
If this
is possible, the substring starting at position pos
of the string s
with a length of len
is appended to the buffer. The actual number
of written bytes is returned.
If no space is available in the buffer, the function fails with a
Unix error of EAGAIN
(non-blocking).
For cancelled requests, the function raises EPERM
.
val close_output_thread : w32_output_thread -> unit
Note that this is also an asynchronous operation, like
output_thread_write
. If closing is not possible at a certain
moment, the Unix error EGAIN
is raised. This ensures that all
errors of previous writes can be reported.
The output thread terminates after a successful close.
For cancelled requests, the function raises EPERM
.
val cancel_output_thread : w32_output_thread -> unit
It is no error to cancel a thread that is already cancelled or closed. There is no way to restart the thread later.
The thread is automatically cancelled by the GC finaliser. However,
users are encouraged to call cancel_output_thread
or
close_output_thread
as soon as
the thread is no longer needed, because a thread is an expensive
resource.
Implementation note: Actually, cancellation is only fully implemented
on Windows Vista. On XP the actual cancellation may be delayed
indefinetely.
val output_thread_proxy_descr : w32_output_thread -> Unix.file_descr
type
create_process_option =
| |
CP_change_directory of |
(* | The initial working directory is set to this path. By default the new process starts with the current working directory of the caller. | *) |
| |
CP_set_env of |
(* | The process environment is set to this encoded array of environment
variables. By default the current environment is passed down
to the new process.
The string is created from an array of "name=value" settings by separating all elements by null bytes, and by putting two null bytes at the end. | *) |
| |
CP_std_handles of |
(* | Sets the standard handles of the new console process. | *) |
| |
CP_create_console |
(* | Creates a new console window. The standard handles of the new
process may also be modified - however, the exact effect is not
well documented by Microsoft. I have the impression that the logic
is this: handles pointing to the parent console are replaced by
handles pointing to the new console. Also, invalid handles
are replaced by handles of the new console. It does not matter how
the standard handles are passed down - either implicitly or by
CP_std_handles . So you cannot create a new console, and
keep standard handles that are connected to the old console.
Best practice is to avoid the combination of CP_std_handles and
CP_create_console when there is already a console.
This flag does not have any effect when the started app is a GUI app. | *) |
| |
CP_detach_from_console |
(* | The new process detaches from the console at startup, even if it is
a console application. Unless CP_std_handles is specified,
the new process will initially not have standard handles (i.e.
the standard handles are invalid handles)!
GUI apps detach from the console anyway. | *) |
| |
CP_inherit_console |
(* | The new console process inherits the console from the caller, if present. Otherwise the new console process starts without console. For GUI apps there is not any effect: They do not have a console anyway. | *) |
| |
CP_inherit_or_create_console |
(* | If present, the console is inherited from the caller. If not present, a new console is created for console applications. This mode is the default. | *) |
| |
CP_unicode_environment |
(* | Indicates that the environment is a Unicode environment | *) |
| |
CP_ansi_environment |
(* | Indicates that the environment is an ANSI environment. This is the default. | *) |
| |
CP_new_process_group |
(* | The new process is run in a new process group | *) |
| |
CP_inherit_process_group |
(* | The new process is run in the same process group as the caller. This is the default | *) |
val cp_set_env : string array -> create_process_option
CP_set_env
option for this array of environment
variables (in the Unix.environment
format)val search_path : string option -> string -> string option -> string
search_path path_opt name ext_opt
: Uses the SearchPath function
to locate a file. If name
does not end with ext_opt
, this
extension is added during the search. If path_opt
is None
,
the default search path is used.type
w32_process
val create_process : string ->
string -> create_process_option list -> w32_process
create_process cmd cmdline options
: Spawns a new process that runs
concurrently with the calling process. cmd
is the command
to execute (it is not searched by path, and the file suffix must be
given). cmdline
is the full command-line.
If the exit code of the new process does not play any role, it is
ok to just ignore the returned process handle (which will be
automatically closed by a GC finalizer).
val close_process : w32_process -> unit
w32_process
value, if it is still openval get_process_status : w32_process -> Unix.process_status option
None
otherwiseval as_process_event : w32_process -> w32_event
event_wait
(above) and
wsa_wait_for_multiple_events
to wait for the termination of the
process.val emulated_pid : w32_process -> int
Unix
library to refer to
processes, especially in waitpid
. Note that the pid is actually
a handle, and it must be closed by calling Unix.waitpid
.
Each call of emulated_pid
returns a new handle.
val win_pid : w32_process -> int
val process_descr : w32_process -> Unix.file_descr
val terminate_process : w32_process -> unit
val has_console : unit -> bool
val is_console : Unix.file_descr -> bool
val get_console_input : unit -> Unix.file_descr
The returned descriptor needs to be closed by the caller when done
with it.
val get_console_output : unit -> Unix.file_descr
The returned descriptor needs to be closed by the caller when done
with it.
type
w32_console_attr = {
|
mutable cursor_x : |
(* | from 0 (leftmost) to width-1 (rightmost) | *) |
|
mutable cursor_y : |
(* | from 0 (topmost) to height-1 (bottommost) | *) |
|
mutable cursor_size : |
(* | from 1 to 100 | *) |
|
mutable cursor_visible : |
|||
|
mutable text_attr : |
type
w32_console_info = {
|
mutable width : |
(* | screen width of the console in chars | *) |
|
mutable height : |
(* | screen height in lines | *) |
val get_console_attr : unit -> w32_console_attr
val set_console_attr : w32_console_attr -> unit
val get_console_info : unit -> w32_console_info
val fg_blue : int
val fg_green : int
val fg_red : int
val fg_intensity : int
val bg_blue : int
val bg_green : int
val bg_red : int
val bg_intensity : int
text_attr
type
w32_console_mode = {
|
mutable enable_echo_input : |
|
mutable enable_insert_mode : |
|
mutable enable_line_input : |
|
mutable enable_processed_input : |
|
mutable enable_quick_edit_mode : |
|
mutable enable_processed_output : |
|
mutable enable_wrap_at_eol_output : |
val get_console_mode : unit -> w32_console_mode
val set_console_mode : w32_console_mode -> unit
val init_console_codepage : unit -> unit
Note, however, that the docs say: "If the current font is a raster font, SetConsoleOutputCP does not affect how extended characters are displayed." (grrmmpf) So you should also switch to a different font - otherwise you get input in the ANSI code page, and do output in the OEM code page.
For Windows novices: Historically, there were two types of 8 bit
character sets. The older type is an IBM code page, and predates
the ISO-8859 series of character sets. This code page was used
at MS-DOS times. Microsoft calls this code page the "OEM" code
page. Later, when ISO-8859 was created, Microsoft switched to
code pages that are similar to this standard, but also do not
fully match them. These newer code pages have names like
"Windows-1252", and are now called ANSI code pages by Microsoft.
The 8-bit versions of the Win32 calls (which are used by the
Ocaml runtime)normally use the ANSI code page.
val clear_until_end_of_line : unit -> unit
val clear_until_end_of_screen : unit -> unit
val clear_console : unit -> unit
val get_active_code_page : unit -> int
Netconversion.win32_code_pages
.w32_event
, w32_pipe
, and w32_pipe_server
)
it is possible
to obtain proxy descriptors. These have type Unix.file_descr
and they
contain a real file handle. The purpose of these descriptors is to
be used as proxy objects that can be passed to functions expecting
file descriptors as input. However, you cannot do anything with the
proxies except looking the corresponding real objects up. Proxy
descriptors are used in interfaces that only allow to pass
Unix.file_descr
values in and out.
Proxy descriptors have to be closed by the caller once they have
been handed out to the caller. Closing the proxy descriptor does not
make the descriptor unusable (lookups still work), and the referenced
object is also
unaffected. It is up to the user when Unix.close
is best called -
it is even allowed to do it immediately after requesting the proxy
descriptor, e.g. via pipe_descr
. After closing the proxy, however,
it is possible that the system generates another file descriptor
that looks equal to the closed proxy. It is often best to close at the
moment when one is really done with the proxy.
type
w32_object =
| |
W32_event of |
| |
W32_pipe of |
| |
W32_pipe_server of |
| |
W32_process of |
| |
W32_input_thread of |
| |
W32_output_thread of |
val lookup : Unix.file_descr -> w32_object
Not_found
. Note that the returned object needs not to be physically
identical to the original object. It behaves, however, exactly the
same way.val lookup_event : Unix.file_descr -> w32_event
val lookup_pipe : Unix.file_descr -> w32_pipe
val lookup_pipe_server : Unix.file_descr -> w32_pipe_server
val lookup_process : Unix.file_descr -> w32_process
val lookup_input_thread : Unix.file_descr -> w32_input_thread
val lookup_output_thread : Unix.file_descr -> w32_output_thread
Failure
is raised.val unregister : Unix.file_descr -> unit
unregister
is optional, and the removal
will take place anyway when the descriptor is collected by the GC.val test_close_on_exec : Unix.file_descr -> bool
val modify_close_on_exec : Unix.file_descr -> bool -> unit
Unix.set_close_on_exec
and Unix.clear_close_on_exec
have a serious problem, and do not always work.val is_crt_fd : Unix.file_descr -> int -> bool
is_crt_fd 0
to check whether fd
is Unix.stdin
(physically)val fill_random : string -> unit
module Debug:sig
..end