module Netsys_win32:Primitives for Win32sig..end
type w32_event
val create_event : unit -> w32_eventval set_event : w32_event -> unitval reset_event : w32_event -> unitval test_event : w32_event -> boolval event_wait : w32_event -> float -> boolval event_descr : w32_event -> Unix.file_descrlookup 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 -> unitval wsa_maximum_wait_events : unit -> intwsa_wait_for_multiple_eventsval wsa_wait_for_multiple_events : w32_event array -> int -> int optionThe 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_eventsval 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 listUnix.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_modeval create_local_pipe_server : string -> pipe_mode -> int -> w32_pipe_servercreate_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 -> unitn prepared server endpoints.
One can check for new client connections by looking at the
pipe_connect_event.
val pipe_accept : w32_pipe_server -> w32_pipeval pipe_connect : string -> pipe_mode -> w32_pipepipe_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_pipepipe_mode, and the
right pipe is in the matching complementaty mode.val pipe_read : w32_pipe -> string -> int -> int -> intpipe_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 -> intpipe_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 -> unitNote 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 -> unitpipe_accepted, it is simply destroyed by this function.val pipe_connect_event : w32_pipe_server -> w32_eventval pipe_rd_event : w32_pipe -> w32_eventval pipe_wr_event : w32_pipe -> w32_eventval pipe_wait_connect : w32_pipe_server -> float -> boolval pipe_wait_rd : w32_pipe -> float -> boolval pipe_wait_wr : w32_pipe -> float -> boolval pipe_server_descr : w32_pipe_server -> Unix.file_descrlookup 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_descrlookup 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 -> stringval pipe_server_name : w32_pipe_server -> stringval pipe_mode : w32_pipe -> pipe_modeval pipe_server_mode : w32_pipe_server -> pipe_modeval unpredictable_pipe_name : unit -> stringpipe_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
I/O threads can be used to do read/write-based I/O in an asynchronous
way for file handles that do not support asynchronous I/O by themselves,
e.g. anonymous pipes.
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_threadinput_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_eventval input_thread_read : w32_input_thread -> string -> int -> int -> intinput_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_descrtype w32_output_thread
val create_output_thread : Unix.file_descr -> w32_output_threadoutput_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_eventval output_thread_write : w32_output_thread -> string -> int -> int -> intoutput_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 -> unitIt 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_optionCP_set_env option for this array of environment
variables (in the Unix.environment format)val search_path : string option -> string -> string option -> stringsearch_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_processcreate_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 -> unitw32_process value, if it is still openval get_process_status : w32_process -> Unix.process_status optionNone
otherwiseval as_process_event : w32_process -> w32_eventevent_wait (above) and
wsa_wait_for_multiple_events to wait for the termination of the
process.val emulated_pid : w32_process -> intUnix 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 -> intval process_descr : w32_process -> Unix.file_descrval terminate_process : w32_process -> unitval has_console : unit -> boolval is_console : Unix.file_descr -> boolval 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_attrval set_console_attr : w32_console_attr -> unitval get_console_info : unit -> w32_console_infoval fg_blue : intval fg_green : intval fg_red : intval fg_intensity : intval bg_blue : intval bg_green : intval bg_red : intval bg_intensity : inttext_attrtype 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_modeval set_console_mode : w32_console_mode -> unitval init_console_codepage : unit -> unitNote, 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 -> unitval clear_until_end_of_screen : unit -> unitval clear_console : unit -> unitval get_active_code_page : unit -> intNetconversion.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_objectNot_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_eventval lookup_pipe : Unix.file_descr -> w32_pipeval lookup_pipe_server : Unix.file_descr -> w32_pipe_serverval lookup_process : Unix.file_descr -> w32_processval lookup_input_thread : Unix.file_descr -> w32_input_threadval lookup_output_thread : Unix.file_descr -> w32_output_threadFailure is raised.val unregister : Unix.file_descr -> unitunregister 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 -> boolval modify_close_on_exec : Unix.file_descr -> bool -> unitUnix.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 -> boolis_crt_fd 0 to check whether fd is Unix.stdin
(physically)val fill_random : string -> unitmodule Debug:sig..end