From 91800b4f0fb1e419c5df3c51564e119d4db39a37 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 3 Jul 2007 22:24:58 +0000
Subject: [PATCH] doc work on os reference

svn: r6813
---
 .../scribblings/reference/file-ports.scrbl    |   2 +-
 collects/scribblings/reference/os.scrbl       |   3 +
 collects/scribblings/reference/read.scrbl     |   2 +-
 collects/scribblings/reference/runtime.scrbl  | 187 ++++++++++++++++
 .../scribblings/reference/subprocess.scrbl    | 200 ++++++++++++++++++
 collects/scribblings/reference/time.scrbl     | 115 ++++++++++
 collects/scribblings/reference/write.scrbl    |   8 +-
 7 files changed, 511 insertions(+), 6 deletions(-)
 create mode 100644 collects/scribblings/reference/runtime.scrbl
 create mode 100644 collects/scribblings/reference/subprocess.scrbl
 create mode 100644 collects/scribblings/reference/time.scrbl

diff --git a/collects/scribblings/reference/file-ports.scrbl b/collects/scribblings/reference/file-ports.scrbl
index 39be321964..94e387c5c5 100644
--- a/collects/scribblings/reference/file-ports.scrbl
+++ b/collects/scribblings/reference/file-ports.scrbl
@@ -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.
diff --git a/collects/scribblings/reference/os.scrbl b/collects/scribblings/reference/os.scrbl
index 5a99cec09b..46e6efed08 100644
--- a/collects/scribblings/reference/os.scrbl
+++ b/collects/scribblings/reference/os.scrbl
@@ -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"]
diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl
index 2a3f8a9dcd..1489bb8e95 100644
--- a/collects/scribblings/reference/read.scrbl
+++ b/collects/scribblings/reference/read.scrbl
@@ -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.
 
diff --git a/collects/scribblings/reference/runtime.scrbl b/collects/scribblings/reference/runtime.scrbl
new file mode 100644
index 0000000000..ee272a9bb1
--- /dev/null
+++ b/collects/scribblings/reference/runtime.scrbl
@@ -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.}
+
+ }
+}
\ No newline at end of file
diff --git a/collects/scribblings/reference/subprocess.scrbl b/collects/scribblings/reference/subprocess.scrbl
new file mode 100644
index 0000000000..f6b81f6f7a
--- /dev/null
+++ b/collects/scribblings/reference/subprocess.scrbl
@@ -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).
diff --git a/collects/scribblings/reference/time.scrbl b/collects/scribblings/reference/time.scrbl
new file mode 100644
index 0000000000..b09d1b292e
--- /dev/null
+++ b/collects/scribblings/reference/time.scrbl
@@ -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].}
diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl
index d8a0b9ba1a..1494a7f4b0 100644
--- a/collects/scribblings/reference/write.scrbl
+++ b/collects/scribblings/reference/write.scrbl
@@ -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?]{