doc work on os reference

svn: r6813
This commit is contained in:
Matthew Flatt 2007-07-03 22:24:58 +00:00
parent a0bc09e232
commit 91800b4f0f
7 changed files with 511 additions and 6 deletions

View File

@ -4,7 +4,7 @@
@title{File Ports}
A port created by @scheme[open-input-file], @scheme[open-output-file],
@scheme[subprocess], and related functions is a @defterm{file-stream
@scheme[subprocess], and related functions is a @deftech{file-stream
port}. The initial input, output, and error ports in stand-alone
MzScheme are also file-stream ports. The @scheme[file-stream-port?]
predicate recognizes file-stream ports.

View File

@ -8,3 +8,6 @@
@include-section["paths.scrbl"]
@include-section["filesystem.scrbl"]
@include-section["networking.scrbl"]
@include-section["subprocess.scrbl"]
@include-section["time.scrbl"]
@include-section["runtime.scrbl"]

View File

@ -231,7 +231,7 @@ arguments:
The default port read handler reads standard Scheme expressions with
Scheme's built-in parser (see @secref["mz:reader"]). It handles a
special result from a custom input port (see
@secref["mz:custominput"]) by treating it as a single expression,
@scheme[make-custom-input-port]) by treating it as a single expression,
except that special-comment values (see
@secref["mz:special-comments"]) are treated as whitespace.

View File

@ -0,0 +1,187 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title{Environment and Runtime Information}
@defproc[(getenv [name string?]) (or/c string? false/c)]{
Gets the value of an operating system environment variable. The
@scheme[name] argument cannot contain a null character; if an
environment variable named by @scheme[name] exists, its value is
returned (as a string); otherwise, @scheme[#f] is returned.}
@defproc[(putenv [name string?][value string?]) boolean?]{
Sets the value of an operating system environment variable. The
@scheme[name] and @scheme[value] arguments are strings that cannot
contain a null character; the environment variable named by
@scheme[name] is set to @scheme[value]. The return value is
@scheme[#t] if the assignment succeeds, @scheme[#f] otherwise.}
@defproc[(system-type [mode (one-of 'os 'gc 'link 'so-suffix 'machine)
'os])
(or/c symbol? string? bytes?)]{
Returns information about the operating system, build mode, or machine
for a running Scheme.
In @scheme['os] mode,
the possible symbol results are:
@itemize{
@item{@scheme['unix]}
@item{@scheme['windows]}
@item{@scheme['macosx]}
}
In @scheme['gc] mode,
the possible symbol results are:
@itemize{
@item{@scheme['cgc]}
@item{@scheme['3m]}
}
In @scheme['link] mode, the possible symbol results are:
@itemize{
@item{@scheme['static] (Unix)}
@item{@scheme['shared] (Unix)}
@item{@scheme['dll] (Windows)}
@item{@scheme['framework] (Mac OS X)}
}
Future ports of Scheme may expand the list of @scheme['os],
@scheme['gc], and @scheme['link] results.
In @scheme['so-suffix] mode, then the result is a byte string that
represents the file extension used for shared objects on the current
platform. The byte string starts with a period, so it is suitable as a
second argument to @scheme[path-replace-suffix].
In @scheme['machine] mode, then the result is a string, which contains
further details about the current machine in a platform-specific
format.}
@defproc[(system-language+country) string?]{
Returns a string to identify the current user's language and
country.
Under Unix and Mac OS X, the string is five characters: two lowercase
ASCII letters for the language, an underscore, and two uppercase ASCII
letters for the country. Under Windows, the string can be arbitrarily
long, but the language and country are in English (all ASCII letters
or spaces) separated by an underscore.
Under Unix, the result is determined by checking the @envvar{LC_ALL},
@envvar{LC_TYPE}, and @envvar{LANG} environment variables, in that
order (and the result is used if the environment variable's value
starts with two lowercase ASCII letters, an underscore, and two
uppercase ASCII letters, followed by either nothing or a
period). Under Windows and Mac OS X, the result is determined by
system calls.}
@defproc[(system-library-subpath [mode (one-of 'cgc '3m #f)
(system-type 'gc)])
path?]{
Returns a relative directory path. This string can be used to build
paths to system-specific files. For example, when Scheme is running
under Solaris on a Sparc architecture, the subpath starts
@scheme["sparc-solaris"], while the subpath for Windows on an i386
architecture starts @scheme["win32\\i386"].
The optional @scheme[mode] argument specifies the relevant
garbage-collection variant, which one of the possible results of
@scheme[(system-type 'gc)]: @scheme['cgc] or @scheme['3m]. It can also
be @scheme[#f], in which case the result is independent of the
garbage-collection variant.}
@defproc[(version) (and/c string? immutable?)]{
Returns an string indicating the currently executing version of
Scheme.}
@defproc[(banner) (and/c string? immutable?)]{
Returns an immutable string for Scheme's start-up banner text (or the
banner text for an embedding program, such as MrEd). The banner string
ends with a newline.}
@defproc[(vector-set-performance-stats! [results (and/c vector?
(not/c immutable?))]
[thd (or/c thread? false/c) #f])
void?]{
Sets elements in @scheme[results] to report current performance
statistics. If @scheme[thd] is not @scheme[#f], a particular set of
thread-specific statistics are reported, otherwise a different set of
global statics are reported.
For global statistics, up to @math{10} elements are set in the vector,
starting from the beginning. (In future versions of Scheme, additional
elements will be set.) If @scheme[results] has @math{n} elements where
@math{n < 8}, then the @math{n} elements are set to the first @math{n}
performance-statistics values. The reported statistics values are as
follows, in the order that they are set within @scheme[results]:
@itemize{
@item{@scheme[0]: The same value as returned by
@scheme[current-process-milliseconds].}
@item{@scheme[1]: The same value as returned
by @scheme[current-milliseconds].}
@item{@scheme[2]: The same value as returned
by @scheme[current-gc-milliseconds].}
@item{@scheme[3]: The number of garbage collections performed since
start-up.}
@item{@scheme[4]: The number of thread context switches performed since
start-up.}
@item{@scheme[5]: The number of internal stack overflows handled since
start-up.}
@item{@scheme[6]: The number of threads currently scheduled for
execution (i.e., threads that are running, not suspended, and not
unscheduled due to a synchronization).}
@item{@scheme[7]: The number of syntax objects read from compiled code
since start-up.}
@item{@scheme[8]: The number of hash-table searches performed.}
@item{@scheme[9]: The number of additional hash slots searched to complete
hash searches (using double hashing).}
}
For thread-specific statistics, up to @math{4} elements are set in the
vector:
@itemize{
@item{@scheme[0]: @scheme[#t] if the thread is running, @scheme[#f]
otherwise (same result as @scheme[thread-running?]).}
@item{@scheme[1]: @scheme[#t] if the thread has terminated,
@scheme[#f] otherwise (same result as @scheme[thread-dead?]).}
@item{@scheme[2]: @scheme[#t] if the thread is currently blocked on a
synchronizable event (or sleeping for some number of milliseconds),
@scheme[#f] otherwise.}
@item{@scheme[3]: The number of bytes currently in use for the
thread's continuation.}
}
}

View File

@ -0,0 +1,200 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title[#:tag "mz:subprocess"]{Processes}
@defproc[(subprocess [stdout (or/c output-port? false/c)]
[stdin (or/c input-port? false/c)]
[stderr (or/c output-port? false/c)]
[command path-string?]
[arg string?] ...)
(values subprocess?
(or/c input-port? false/c)
(or/c output-port? false/c)
(or/c input-port? false/c))]{
Creates a new process in the underlying operating system to execute
@scheme[command] asynchronously. The @scheme[command] argument is a
path to a program executable, and the @scheme[arg]s are command-line
arguments for the program. Under Unix and Mac OS X, command-line
arguments are passed as byte strings using the current locale's
encoding (see @secref["mz:encodings"]).
Under Windows, the first @scheme[arg] can be @scheme['exact], which
triggers a Windows-specific hack: the second @scheme[arg] is used
exactly as the command-line for the subprocess, and no additional
@scheme[arg]s can be supplied. Otherwise, a command-line string is
constructed from @scheme[command] and @scheme[arg] so that a typical
Windows console application can parse it back to an array of
arguments. If @scheme['exact] is provided on a non-Windows platform,
the @exnraise[exn:fail:contract].
@margin-note{For information on the Windows command-line conventions,
search for ``command line parsing'' at
@tt{http://msdn.microsoft.com/}.}
Unless it is @scheme[#f], @scheme[stdout] is used for the launched
process's standard output, @scheme[stdin] is used for the process's
standard input, and @scheme[stderr] is used for the process's standard
error. All provided ports must be file-stream ports. Any of the ports
can be @scheme[#f], in which case a system pipe is created and
returned by @scheme[subprocess]. For each port that is provided, no
pipe is created and the corresponding returned value is @scheme[#f].
The @scheme[subprocess] procedure returns four values:
\begin{itemize}
@item{a subprocess value representing the created process;}
@item{an input port piped from the process's standard output, or
@scheme[#f] if @scheme[stdout-output-port] was a port;}
@item{an output port piped to the process standard input, or
@scheme[#f] if @scheme[stdin-input-port] was a port;}
@item{an input port piped from the process's standard error, or
@scheme[#f] if @scheme[stderr-output-port] was a port.}
}
@bold{Important:} All ports returned from @scheme[subprocess] must be
explicitly closed with @scheme[close-input-port] or
@scheme[close-output-port].
The returned ports are @tech{file-stream ports} (see
@secref["mz:file-ports"]), and they are placed into the management of
the current custodian (see @secref["mz:custodians"]). The
@exnraise[exn:fail] when a low-level error prevents the spawning of a
process or the creation of operating system pipes for process
communication.
@defproc[(subprocess-wait [subproc subprocess?]) void?]{
Blocks until the process represented by @scheme[subproc] terminates.}
@defproc[(subprocess-status [subproc subprocess?])
(or/c (one-of/c 'running)
nonnegative-exact-integer?)]{
Returns @scheme['running] if the process represented by @scheme[subproc] is still running, or its exit
code otherwise. The exit code is an exact integer, and @scheme[0]
typically indicates success. If the process terminated due to a fault
or signal, the exit code is non-zero.}
@defproc[(subprocess-kill [subproc subprocess?][force? any/c]) void?]{
Terminates the subprocess represented by @scheme[subproc] if
@scheme[force?] is true and if the process still running. If an error
occurs during termination, the @exnraise[exn:fail].
If @scheme[force?] is @scheme[#f] under @|AllUnix|, the subprocess is
sent an interrupt signal instead of a kill signal (and the subprocess
might handle the signal without terminating). Under Windows, no action
is taken when @scheme[force?] is @scheme[#f].}
@defproc[(subprocess-pid [subproce subprocess?]) nonnegative-exact-integer?]{
Returns the operating system's numerical ID (if any) for the process
represented by @scheme[subproc], valid only as long as the process is
running.}
@defproc[(subprocess? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a subprocess value, @scheme[#f]
otherwise.}
@defproc[(shell-execute [verb (or/c string? false/c)]
[target string?][parameters string?][dir path-string?][show-mode symbol?])
false/c]
@index['("ShellExecute")]{Performs} the action specified by
@scheme[verb] on @scheme[target] in Windows. For platforms other than
Windows, the @exnraise[exn:fail:unsupported].
For example,
@schemeblock[
(shell-execute #f "http://www.plt-scheme.org" ""
(current-directory) 'sw_shownormal)
]
Opens the PLT Scheme home page in a browser window.
The @scheme[verb] can be @scheme[#f], in which case the operating
system will use a default verb. Common verbs include @scheme["open"],
@scheme["edit"], @scheme["find"], @scheme["explore"], and
@scheme["print"].
The @scheme[target] is the target for the action, usually a filename
path. The file could be executable, or it could be a file with a
recognized extension that can be handled by an installed application.
The @scheme[parameters] argument is passed on to the system to perform
the action. For example, in the case of opening an executable, the
@scheme[parameters] is used as the command line (after the executable
name).
The @scheme[dir] is used as the current directory when performing the
action.
The @scheme[show-mode] sets the display mode for a Window affected by
the action. It must be one of the following symbols; the description
of each symbol's meaning is taken from the Windows API documentation.
@itemize{
@item{@scheme['sw_hide] or @scheme['SW_HIDE] --- Hides the window and
activates another window.}
@item{@scheme['sw_maximize] or @scheme['SW_MAXIMIZE] --- Maximizes
the window.}
@item{@scheme['sw_minimize] or @scheme['SW_MINIMIZE] --- Minimizes
the window and activates the next top-level window in the z-order.}
@item{@scheme['sw_restore] or @scheme['SW_RESTORE] --- Activates and
displays the window. If the window is minimized or maximized, Windows
restores it to its original size and position.}
@item{@scheme['sw_show] or @scheme['SW_SHOW] --- Activates the window
and displays it in its current size and position.}
@item{@scheme['sw_showdefault] or @scheme['SW_SHOWDEFAULT] --- Uses a
default.}
@item{@scheme['sw_showmaximized] or @scheme['SW_SHOWMAXIMIZED] ---
Activates the window and displays it as a maximized window.}
@item{@scheme['sw_showminimized] or @scheme['SW_SHOWMINIMIZED] ---
Activates the window and displays it as a minimized window.}
@item{@scheme['sw_showminnoactive] or @scheme['SW_SHOWMINNOACTIVE]
--- Displays the window as a minimized window. The active window
remains active.}
@item{@scheme['sw_showna] or @scheme['SW_SHOWNA] --- Displays the
window in its current state. The active window remains active.}
@item{@scheme['sw_shownoactivate] or @scheme['SW_SHOWNOACTIVATE] ---
Displays a window in its most recent size and position. The active
window remains active.}
@item{@scheme['sw_shownormal] or @scheme['SW_SHOWNORMAL] ---
Activates and displays a window. If the window is minimized or
maximized, Windows restores it to its original size and position.}
}
If the action fails, the @exnraise[exn:fail]. If the action succeeds,
the result is @scheme[#f].
In future versions of Scheme, the result may be a subprocess value if
the operating system did returns a process handle (but if a subprocess
value is returned, its process ID will be @scheme[0] instead of the
real process ID).

View File

@ -0,0 +1,115 @@
#reader(lib "docreader.ss" "scribble")
@require["mz.ss"]
@title[#:tag "mz:time"]{Time}
@defproc[(current-seconds) exact-integer?]{
Returns the current time in seconds. This time is always an exact
integer based on a platform-specific starting date (with a
platform-specific minimum and maximum value).
The value of @scheme[(current-seconds)] increases as time passes
(increasing by 1 for each second that passes). The current time in
seconds can be compared with a time returned by
@scheme[file-or-directory-modify-seconds].}
@defproc[(seconds->date [secs-n exact-integer?]) date?]{
Takes @scheme[secs-n], a platform-specific time in seconds returned by
@scheme[current-seconds] or @scheme[file-or-directory-modify-seconds],
and returns an instance of the @scheme[date] structure type. If
@scheme[secs-n] is too small or large, the @exnraise[exn:fail].
The value returned by @scheme[current-seconds] or
@scheme[file-or-directory-modify-seconds] is not portable among
platforms. Convert a time in seconds using @scheme[seconds->date] when
portability is needed.}
@defstruct[date ([second (integer-in 0 61)]
[minute (integer-in 0 59)]
[hour (integer-in 0 23)]
[day (integer-in 1 31)]
[month (integer-in 1 12)]
[year nonnegative-exact-integer?]
[week-day (integer-in 0 6)]
[year-day (integer-in 0 365)]
[dst? boolean?]
[time-zone-offset exact-integer?])
#:inspector #f]{
Represents a date. For the @scheme[second] field, values of
@scheme[60] and @scheme[61] are for unusual, but possible for
leap-seconds. The @scheme[year-day] field reaches @scheme[365] only in
leap years.
The @scheme[time-zone-offset] field reports the number of seconds east
of GMT for the current time zone (e.g., Pacific Standard Time is
@scheme[-28800]), an exact integer.
The value produced for the @scheme[time-zone-offset] field tends to be
sensitive to the value of the @envvar{TZ} environment variable,
especially on Unix platforms; consult the system documentation
(usually under @tt{tzset}) for details.}
@defproc[(current-milliseconds) exact-integer?]{
Returns the current ``time'' in fixnum milliseconds (possibly
negative). This time is based on a platform-specific starting date or
on the machine's startup time. Since the result is a fixnum, the value
increases only over a limited (though reasonably long) time.}
@defproc[(current-inexact-milliseconds) real?]{
Returns the current ``time'' in positive milliseconds, not necessarily
an integer. This time is based on a platform-specific starting date or
on the machine's startup time, but it never decreases (until the
machine is turned off).}
@defproc[(current-process-milliseconds) exact-integer?]{
Returns the amount of processor time in fixnum milliseconds that has
been consumed by the Scheme process on the underlying operating
system. (Under @|AllUnix|, this includes both user and system time.)
The precision of the result is platform-specific, and since the result
is a fixnum, the value increases only over a limited (though
reasonably long) time.}
@defproc[(current-gc-milliseconds) exact-integer?]{
Returns the amount of processor time in fixnum milliseconds that has
been consumed by Scheme's garbage collection so far. This time is a
portion of the time reported by
@scheme[(current-process-milliseconds)].}
@defproc[(time-apply [proc procedure?]
[arg any/c] ...)
(values exact-integer?
exact-integer?
exact-integer?
list?)]{
Collects timing information for a procedure application.
Four values are returned: a list containing the result(s) of applying
@scheme[proc], the number of milliseconds of CPU time required to
obtain this result, the number of ``real'' milliseconds required for
the result, and the number of milliseconds of CPU time (included in
the first result) spent on garbage collection.
The reliability of the timing numbers depends on the platform. If
multiple MzScheme threads are running, then the reported time may
include work performed by other threads.}
@defform[(time expr)]{
Reports @scheme[time-apply]-style timing information for the
evaluation of @scheme[expr] directly to the current output port. The
result is the result of @scheme[expr].}

View File

@ -15,7 +15,7 @@ handler associated to it via @scheme[port-write-handler], then the
handler is called. Otherwise, the default printer is used (in
@scheme[write] mode), as configured by various parameters.
See @secref["mz:printer"] for more information about the default
See @secref["mz:printing"] for more information about the default
printer. In particular, note that @scheme[write] may require memory
proportional to the depth of the value being printed, due to the
initial cycle check.}
@ -30,7 +30,7 @@ associated to it via @scheme[port-display-handler], then the handler
is called. Otherwise, the default printer is used (in @scheme[display]
mode), as configured by various parameters.
See @secref["mz:printer"] for more information about the default
See @secref["mz:printing"] for more information about the default
printer. In particular, note that @scheme[display] may require memory
proportional to the depth of the value being printed, due to the
initial cycle check.}
@ -137,7 +137,7 @@ Formats to a string. The result is the same as
A parameter that controls printing values that have no
@scheme[read]able form (using the default reader), including
structures that have a custom-write procedure (see
@secref["mz:custom-write"]); defaults to @scheme[#t]. See
@scheme[prop:custom-write]); defaults to @scheme[#t]. See
@secref["mz:printing"] for more information.}
@defboolparam[print-graph on?]{
@ -151,7 +151,7 @@ A parameter that controls printing structure values in vector form;
defaults to @scheme[#t]. See @secref["mz:printing"] for more
information. This parameter has no effect on the printing of
structures that have a custom-write procedure (see
@secref["mz:custom-write"]).}
@scheme[prop:custom-write]).}
@defboolparam[print-box on?]{