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