r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

system-interface.texinfo (6949B)


      1 @node System interface
      2 @section System interface
      3 
      4 Questions of system interface generally fall outside of the domain of
      5 this report. However, the following operations are important enough to
      6 deserve description here.
      7 
      8 @deffn  {load library procedure} load filename
      9 @deffnx {load library procedure} load filename environment-specifier
     10 
     11 It is an error if @var{filename} is not a string.
     12 
     13 An implementation-dependent operation is used to
     14 transform @var{filename} into the name of an existing
     15 file containing Scheme source code.  The @code{load}
     16 procedure reads expressions and definitions from the file and
     17 evaluates them sequentially in the environment specified by
     18 @var{environment-specifier}.  If @var{environment-specifier} is
     19 omitted, @code{(interaction-environment)} is assumed.
     20 
     21 It is unspecified whether the results of the expressions are printed.
     22 The @code{load} procedure does not affect the values returned by
     23 @code{current-input-port} and @code{current-output-port}.  It returns
     24 an unspecified value.
     25 
     26 @rationale{}
     27 
     28 For portability, @code{load} must operate on source files.
     29 Its operation on other kinds of files necessarily varies among
     30 implementations.
     31 
     32 @end deffn
     33 
     34 @deffn {file library procedure} file-exists? filename
     35 
     36 It is an error if @var{filename} is not a string.
     37 
     38 The @code{file-exists?} procedure returns @code{#t} if the named file
     39 exists at the time the procedure is called, and @code{#f} otherwise.
     40 
     41 @end deffn
     42 
     43 @deffn {file library procedure} delete-file filename
     44 
     45 It is an error if @var{filename} is not a string.
     46 
     47 The @code{delete-file} procedure deletes the named file if it
     48 exists and can be deleted, and returns an unspecified value.  If the
     49 file does not exist or cannot be deleted, an error that satisfies
     50 @code{file-error?} is signaled.
     51 
     52 @end deffn
     53 
     54 @deffn {process-context library procedure} command-line
     55 
     56 Returns the command line passed to the process as a list of
     57 strings. The first string corresponds to the command name, and is
     58 implementation-dependent. It is an error to mutate any of these
     59 strings.
     60 
     61 @end deffn
     62 
     63 @deffn  {process-context library procedure} exit
     64 @deffnx {process-context library procedure} exit obj
     65 
     66 Runs all outstanding dynamic-wind @var{after} procedures, terminates
     67 the running program, and communicates an exit value to the operating
     68 system.  If no argument is supplied, or if @var{obj} is @code{#t},
     69 the @code{exit} procedure should communicate to the operating system
     70 that the program exited normally.  If @var{obj} is @code{#f}, the
     71 @code{exit} procedure should communicate to the operating system
     72 that the program exited abnormally.  Otherwise, @code{exit} should
     73 translate @var{obj} into an appropriate exit value for the operating
     74 system, if possible.
     75 
     76 The @code{exit} procedure must not signal an exception or return to
     77 its continuation.
     78 
     79 Note: Because of the requirement to run handlers, this procedure is
     80 not just the operating system's exit procedure.
     81 
     82 @end deffn
     83 
     84 @deffn  {process-context library procedure} emergency-exit
     85 @deffnx {process-context library procedure} emergency-exit obj
     86 
     87 Terminates the program without running any outstanding dynamic-wind
     88 @var{after} procedures and communicates an exit value to the operating
     89 system in the same manner as @code{exit}.
     90 
     91 @end deffn
     92 
     93 @deffn {process-context library procedure} get-environment-variable name
     94 
     95 Many operating systems provide each running process with an
     96 @define{environment} consisting of @define{environment variables}.  (This
     97 environment is not to be confused with the Scheme environments that
     98 can be passed to @code{eval}: see @ref{Environments and evaluation}.)
     99 Both the name and value of an environment variable are strings.
    100 The procedure @code{get-environment-variable} returns the value of the
    101 environment variable @var{name}, or @code{#f} if the named environment
    102 variable is not found.  It may use locale information to encode the
    103 name and decode the value of the environment variable.  It is an
    104 error if @code{get-environment-variable} can't decode the value.
    105 It is also an error to mutate the resulting string.
    106 
    107 @lisp
    108 (get-environment-variable "PATH")
    109     @result{} "/usr/local/bin:/usr/bin:/bin"
    110 @end lisp
    111 @end deffn
    112 
    113 @deffn {process-context library procedure} get-environment-variables
    114 
    115 Returns the names and values of all the environment variables as an
    116 alist, where the car of each entry is the name of an environment
    117 variable and the cdr is its value, both as strings. The order of the
    118 list is unspecified. It is an error to mutate any of these strings or
    119 the alist itself.
    120 
    121 @lisp
    122 (get-environment-variables)
    123     @result{} (("USER" . "root") ("HOME" . "/"))
    124 @end lisp
    125 @end deffn
    126 
    127 @deffn {time library procedure} current-second
    128 
    129 Returns an inexact number representing the current time on the
    130 International Atomic Time (TAI) scale. The value 0.0 represents
    131 midnight on January 1, 1970 TAI (equivalent to 8.000082 seconds before
    132 midnight Universal Time) and the value 1.0 represents one TAI second
    133 later. Neither high accuracy nor high precision are required; in
    134 particular, returning Coordinated Universal Time plus a suitable
    135 constant might be the best an implementation can do.
    136 
    137 As of 2018, a TAI-UTC offset table can be found at [@ref{TAI}].
    138 @end deffn
    139 
    140 @deffn {time library procedure} current-jiffy
    141 
    142 Returns the number of @define{jiffies} as an exact integer that have
    143 elapsed since an arbitrary, implementation-defined epoch. A jiffy is an
    144 implementation-defined fraction of a second which is defined by the
    145 return value of the @code{jiffies-per-second} procedure. The starting
    146 epoch is guaranteed to be constant during a run of the program, but may
    147 vary between runs.
    148 
    149 @rationale{}
    150 
    151 Jiffies are allowed to be implementation-dependent so that
    152 @code{current-jiffy} can execute with minimum overhead. It should be
    153 very likely that a compactly represented integer will suffice as the
    154 returned value. Any particular jiffy size will be inappropriate for
    155 some implementations: a microsecond is too long for a very fast
    156 machine, while a much smaller unit would force many implementations to
    157 return integers which have to be allocated for most calls, rendering
    158 @code{current-jiffy} less useful for accurate timing measurements.
    159 
    160 @end deffn
    161 
    162 @deffn {time library procedure} jiffies-per-second
    163 
    164 Returns an exact integer representing the number of jiffies per SI
    165 second. This value is an implementation-specified constant.
    166 
    167 @lisp
    168 (define (time-length)
    169   (let ((list (make-list 100000))
    170         (start (current-jiffy)))
    171     (length list)
    172     (/ (- (current-jiffy) start)
    173        (jiffies-per-second))))
    174 @end lisp
    175 @end deffn
    176 
    177 @deffn procedure features
    178 
    179 Returns a list of the feature identifiers which cond-expand treats as
    180 true. It is an error to modify this list. Here is an example of what
    181 @code{features} might return:
    182 
    183 @lisp
    184 (features) @result{}
    185   (r7rs ratios exact-complex full-unicode
    186    gnu-linux little-endian
    187    fantastic-scheme
    188    fantastic-scheme-1.0
    189    space-ship-control-system)
    190 @end lisp
    191 @end deffn