# 14.7 Custodians
A [structure type property](structprops.html#%28tech._structure._type._property%29) that allows structure types to customize the result of [object-name](#%28def._%28%28quote._~23~25kernel%29._object-name%29%29) applied to their instances. The property value can be any of the following:
-   A procedure proc of one argument: In this case, procedure proc receives the structure as an argument, and the result of proc is the [object-name](#%28def._%28%28quote._~23~25kernel%29._object-name%29%29) of the structure.
-   An exact, non-negative integer between 0 (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields): The integer identifies a field in the structure, and the field must be designated as immutable. The value of the field is used as the [object-name](#%28def._%28%28quote._~23~25kernel%29._object-name%29%29) of the structure.
Added in version 6.2 of package base.
------------------------------------------------------------------------


# 14.10 Code Inspectors


### 14.10 Code Inspectors
In the same way that inspectors control access to structure fields (see [Structure Inspectors](inspectors.html)), inspectors also control access to [module bindings](syntax-model.html#%28tech._module._binding%29). Inspectors used this way are code inspectors. The default code inspector for [module bindings](syntax-model.html#%28tech._module._binding%29) is determined by the [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29) parameter, instead of the [current-inspector](inspectors.html#%28def._%28%28quote._~23~25kernel%29._current-inspector%29%29) parameter.


# 14.10 Code Inspectors
When a [module](module.html#%28form._%28%28quote._~23~25kernel%29._module%29%29) declaration is evaluated, the value of the [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29) parameter is associated with the module declaration. When the module is invoked via [require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) or [dynamic-require](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29), a sub-inspector of the module’s declaration-time inspector is created, and this sub-inspector is associated with the module invocation. Any inspector that controls the sub-inspector (including the declaration-time inspector and its superior) controls the module invocation. In particular, if the value of [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29) never changes, then no control is lost for any module invocation, since the module’s invocation is associated with a sub-inspector of [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29).


# 14.10 Code Inspectors
When an inspector that controls a module invocation is installed with [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29), it enables using [module->namespace](Namespaces.html#%28def._%28%28quote._~23~25kernel%29._module-~3enamespace%29%29) on the module, and it enables access to the module’s protected exports (i.e., those identifiers exported from the module with [protect-out](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._protect-out%29%29)) via [dynamic-require](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29). A module cannot [require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) a module that has a weaker declaration-time code inspector.


# 14.10 Code Inspectors
When a [module](module.html#%28form._%28%28quote._~23~25kernel%29._module%29%29) form is expanded or a [namespace](syntax-model.html#%28tech._namespace%29) is created, the value of [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29) is associated with the module or namespace’s top-level [lexical information](syntax-model.html#%28tech._lexical._information%29). Syntax objects with that [lexical information](syntax-model.html#%28tech._lexical._information%29) gain access to the protected and unexported bindings of any module that the inspector controls. In the case of a [module](module.html#%28form._%28%28quote._~23~25kernel%29._module%29%29), the inspector sticks with such syntax objects even the syntax object is used in the expansion of code in a less powerful context; furthermore, if the syntax object is an identifier that is compiled as a variable reference, the inspector sticks with the variable reference even if it appears in a module form that is evaluated (i.e., declared) with a weaker inspector. When a syntax object or variable reference is within compiled code that is printed (see [Printing Compiled Code](printing.html#%28part._print-compiled%29)), the associated inspector is not preserved.


# 14.10 Code Inspectors
When compiled code in printed form is [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) back in, no inspectors are associated with the code. When the code is [eval](eval.html#%28def._%28%28quote._~23~25kernel%29._eval%29%29)uated, the instantiated syntax-object literals and module-variable references acquire value of [current-code-inspector](#%28def._%28%28quote._~23~25kernel%29._current-code-inspector%29%29) as their inspector.
When a module instantiation is attached to multiple [namespaces](syntax-model.html#%28tech._namespace%29), each with its own [module registry](syntax-model.html#%28tech._module._registry%29), the inspector for the module invocation can be registry-specific. The invocation inspector in a particular module registry can be changed via [namespace-unprotect-module](Namespaces.html#%28def._%28%28quote._~23~25kernel%29._namespace-unprotect-module%29%29) (but changing the inspector requires control over the old one).
Changed in version 8.1.0.8 of package base: Added constraint against [require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) of a module with a weaker code inspector.
> ```
(current-code-inspector)	→
(-> current-code-inspector insp)
(current-code-inspector insp) → void?
    insp	:
(-> current-code-inspector insp)


# 14.10 Code Inspectors
```
A parameter that determines an inspector to control access to module bindings and redefinitions.

If the code inspector is changed from its original value, then bytecode loaded by the default compiled-load handler is marked as non-runnable.

------------------------------------------------------------------------

# 14.11 Plumbers

### 14.11 Plumbers

A plumber supports flush callbacks, which are normally triggered just before a Racket process or place exits. For example, a flush callback might flush an output port’s buffer.

> > > Flush callbacks are roughly analogous to the standard C library’s atexit, but flush callback can also be used in other, similar scenarios.

There is no guarantee that a flush callback will be called before a process terminates—either because the plumber is not the original plumber that is flushed by the default exit handler, or because the process is terminated forcibly (e.g., through a custodian shutdown).

> ```
(plumber? v)   →   boolean?
  v : any/c```

Returns #t if v is a [plumber](#%28tech._plumber%29) value, #f otherwise.

Added in version 6.0.1.8 of package base.

> ```
(make-plumber)  →  plumber?
```
(current-plumber)	→
(-> current-plumber plumber)
(current-plumber plumber) → void?
    plumber	:
(-> current-plumber plumber)```


# 14.10 Code Inspectors
A [parameter](eval-model.html#%28tech._parameter%29) that determines a current plumber for [flush callbacks](#%28tech._flush._callback%29). For example, creating an output [file stream port](file-ports.html#%28tech._file._stream._port%29) registers a [flush callback](#%28tech._flush._callback%29) with the [current plumber](#%28tech._current._plumber%29) to flush the port as long as the port is opened.
Added in version 6.0.1.8 of package base.
> ```
(parameter)	→
```
Calls all flush callbacks that are registered with plumber.

The flush callbacks to call are collected from plumber before the first one is called. If a flush callback registers a new flush callback, the new one is not called. If a flush callback raises an exception or otherwise escapes, then the remaining flush callbacks are not called.

Added in version 6.0.1.8 of package base.

> ```
(plumber-flush-handle? v)   →   boolean?
  v : any/c```

Returns #t if v is a flush handle represents the registration of a [flush callback](#%28tech._flush._callback%29), #f otherwise.

Added in version 6.0.1.8 of package base.

> ```
(plumber-add-flush! plumber proc [weak?) → plumber-flush-handle?
  plumber : plumber?
  proc : (plumber-flush-handle? .  →  . any)
  weak? : any/c = #f
```
(parameter)	→```
Unregisters the [flush callback](#%28tech._flush._callback%29) that was registered by the [plumber-add-flush!](#%28def._%28%28quote._~23~25kernel%29._plumber-add-flush%21%29%29) call that produced handle.


# 14.10 Code Inspectors
If the registration represented by handle has been removed already, then [plumber-flush-handle-remove!](#%28def._%28%28quote._~23~25kernel%29._plumber-flush-handle-remove%21%29%29) has no effect.
Added in version 6.0.1.8 of package base.
------------------------------------------------------------------------


# 14.12 Sandboxed Evaluation


### 14.12 Sandboxed Evaluation
|                                                                                |                                                                                |
|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/sandbox]()) |  package: [sandbox-lib](https://pkgs.racket-lang.org/package/sandbox-lib "Install this package using `raco pkg install sandbox-lib`") |
The bindings documented in this section are provided by the [racket/sandbox]() library, not [racket/base](index.html) or [racket](index.html).
The [racket/sandbox]() module provides utilities for creating “sandboxed” evaluators, which are configured in a particular way and can have restricted resources (memory and time), filesystem and network access, and much more. Sandboxed evaluators can be configured through numerous parameters — and the defaults are set for the common use case where sandboxes are very limited.
> ```
(parameter)	→
(-> any/c . → . any)


# 14.12 Sandboxed Evaluation
```
(transitively)	→
(-> exn:fail:sandbox-terminated-reason exn)```

A predicate and accessor for exceptions that are raised when a sandbox is terminated. Once a sandbox raises such an exception, it will continue to raise it on further evaluation attempts.

#### 14.12.1 Security Considerations

Although the sandbox is designed to provide a safe environment for executing Racket programs with restricted access to system resources, executing untrusted programs in a sandbox still carries some risk. Because a malicious program can exercise arbitrary functionality from the Racket runtime and installed collections, an attacker who identifies a vulnerability in Racket or an installed collection may be able to escape the sandbox.

To mitigate this risk, programs that use the sandbox should employ additional precautions when possible. Suggested measures include:

-   Supplying a custom module language to [make-evaluator](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._make-evaluator%29%29) or [make-module-evaluator](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._make-module-evaluator%29%29) that gives untrusted code access to only the language constructs it absolutely requires.

-   If untrusted code needs access to installed collections, installing only the collections required by your program.

-   Using operating-system-level security features to provide defense-in-depth in case the process running the sandbox is compromised.

-   Making sure your Racket installation and installed packages are up-to-date with the latest release.

#### 14.12.2 Customizing Evaluators

The sandboxed evaluators that [make-evaluator](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._make-evaluator%29%29) creates can be customized via many parameters. Most of the configuration parameters affect newly created evaluators; changing them has no effect on already-running evaluators.

The default configuration options are set for a very restricted sandboxed environment — one that is safe to make publicly available. Further customizations might be needed in case more privileges are needed, or if you want tighter restrictions. Another useful approach for customizing an evaluator is to begin with a relatively unrestricted configuration and add the desired restrictions. This approach is made possible by the [call-with-trusted-sandbox-configuration](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-trusted-sandbox-configuration%29%29) function.

The sandbox environment uses two notions of restricting the time that evaluations takes: [shallow time](#%28tech._shallow._time%29) and [deep time](#%28tech._deep._time%29). Shallow time refers to the immediate execution of an expression. For example, a [shallow time](#%28tech._shallow._time%29) limit of five seconds would restrict ([sleep](threads.html#%28def._%28%28quote._~23~25kernel%29._sleep%29%29) 6) and other computations that take longer than five seconds. Deep time refers to the total execution of the expression and all threads and sub-processes that the expression creates. For example, a [deep time](#%28tech._deep._time%29) limit of five seconds would restrict ([thread](threads.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._thread%29%29) ([λ](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._~ce~bb%29%29) () ([sleep](threads.html#%28def._%28%28quote._~23~25kernel%29._sleep%29%29) 6))), which [shallow time](#%28tech._shallow._time%29) would not, as well as all expressions that [shallow time](#%28tech._shallow._time%29) would restrict. By default, most sandboxes only restrict [shallow time](#%28tech._shallow._time%29) to facilitate expressions that use threads.

> ```
(call-with-trusted-sandbox-configuration thunk)  →  any
  thunk : (  →   any)
```


# 14.12 Sandboxed Evaluation
(sandbox-init-hook)	→
(-> any)
(sandbox-init-hook thunk) → void?
    thunk	:
(-> any)```
A [parameter](eval-model.html#%28tech._parameter%29) that determines a thunk to be called for initializing a new evaluator. The hook is called just before the program is evaluated in a newly-created evaluator context. It can be used to setup environment parameters related to reading, writing, evaluation, and so on. Certain languages ('(special r5rs) and the teaching languages) have initializations specific to the language; the hook is used after that initialization, so it can override settings.
> ```
(sandbox-reader)	→
(-> any/c . → . any)
(sandbox-reader proc) → void?
    proc	:
(-> any/c . → . any)


# 14.12 Sandboxed Evaluation
```
(current-input-port)	→
(-> or/c #f
    string? bytes?
    input-port?
    ' pipe
    (→ input-port?))```

A [parameter](eval-model.html#%28tech._parameter%29) that determines the initial [current-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29) setting for a newly created evaluator. It defaults to #f, which creates an empty port. The following other values are allowed:

-   a string or byte string, which is converted to a port using [open-input-string](stringport.html#%28def._%28%28quote._~23~25kernel%29._open-input-string%29%29) or [open-input-bytes](stringport.html#%28def._%28%28quote._~23~25kernel%29._open-input-bytes%29%29);

-   an input port;

-   the symbol 'pipe, which triggers the creation of a pipe, where [put-input](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._put-input%29%29) can return the output end of the pipe or write directly to it;

-   a thunk, which is called to obtain a port (e.g., using [current-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29) means that the evaluator input is the same as the calling context’s input).

> ```
(sandbox-output)	→
(-> or/c #f
    output-port?
    ' pipe
    ' bytes
    ' string
    (→ output-port?))
(sandbox-output in) → void?
    in	:
(-> or/c #f
    output-port?
    ' pipe
    ' bytes
    ' string
    (→ output-port?))
```


# 14.12 Sandboxed Evaluation
(sandbox-error-output)	→
(-> or/c #f
    output-port?
    ' pipe
    ' bytes
    ' string
    (→ output-port?))
(sandbox-error-output in) → void?
    in	:
(-> or/c #f
    output-port?
    ' pipe
    ' bytes
    ' string
    (→ output-port?))```
Like [sandbox-output](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-output%29%29), but for the initial [current-error-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29) value. An evaluator’s error output is set after its output, so using [current-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29) (the parameter itself, not its value) for this parameter value means that the error port is the same as the evaluator’s initial output port.
The default is ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) () ([dup-output-port](port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._dup-output-port%29%29) ([current-error-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29)))), which means that the error output of the generated evaluator goes to the calling context’s error port.
> ```
(sandbox-coverage-enabled)	→
(-> sandbox-coverage-enabled enabled?)


# 14.12 Sandboxed Evaluation
```
(sandbox-propagate-breaks)	→
(-> sandbox-propagate-breaks propagate?)```

When both this boolean parameter and ([break-enabled](breakhandler.html#%28def._%28%28quote._~23~25kernel%29._break-enabled%29%29)) are true, breaking while an evaluator is running propagates the break signal to the sandboxed context. This makes the sandboxed evaluator break, typically, but beware that sandboxed evaluation can capture and avoid the breaks (so if safe execution of code is your goal, make sure you use it with a time limit). Also, beware that a break may be received after the evaluator’s result, in which case the evaluation result is lost. Finally, beware that a break may be propagated after an evaluator has produced a result, so that the break is visible on the next interaction with the evaluator (or the break is lost if the evaluator is not used further). The default is #t.

> ```
(sandbox-propagate-exceptions)	→
(-> sandbox-propagate-exceptions propagate?)
```
(sandbox-namespace-specs)	→
(-> cons/c (→ namespace?)
    (listof module-path?))
(sandbox-namespace-specs spec) → void?
    spec	:
(-> cons/c (→ namespace?)
    (listof module-path?))```


# 14.12 Sandboxed Evaluation
A [parameter](eval-model.html#%28tech._parameter%29) that holds a list of values that specify how to create a namespace for evaluation in [make-evaluator](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._make-evaluator%29%29) or [make-module-evaluator](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._make-module-evaluator%29%29). The first item in the list is a thunk that creates the namespace, and the rest are module paths for modules to be attached to the created namespace using [namespace-attach-module](Namespaces.html#%28def._%28%28quote._~23~25kernel%29._namespace-attach-module%29%29).
The default is ([list](pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29) [sandbox-make-namespace](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-make-namespace%29%29)).
The module paths are needed for sharing module instantiations between the sandbox and the caller. For example, sandbox code that returns posn values (from the lang/posn module) will not be recognized as such by your own code by default, since the sandbox will have its own instance of lang/posn and thus its own struct type for posns. To be able to use such values, include 'lang/posn in the list of module paths.
When testing code that uses a teaching language, the following piece of code can be helpful:
> ```racket
> ( sandbox-namespace-specs
> ( let ( [ specs ( sandbox-namespace-specs ) ] )
> ` ( , ( car specs )
> ,@ ( cdr specs )
> lang/posn
> ,@ ( if ( gui-available? ) ' ( mrlib/cache-image-snip ) ' ( ) ) ) ) )
> ```
> ```
(sandbox-make-namespace)  →  namespace?


# 14.12 Sandboxed Evaluation
```
Calls make-gui-namespace when (sandbox-gui-available) produces true, make-base-namespace otherwise.

> ```
(sandbox-gui-available)	 →
(  →  sandbox-gui-available avail?)```

Determines whether the [racket/gui](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=gui&rel=index.html&version=8.18.0.13) module can be used when a sandbox evaluator is created. If [gui-available?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=gui&rel=Dynamic_Loading.html%23%2528def._%2528%2528lib._racket%252Fgui%252Fdynamic..rkt%2529._gui-available%7E3f%2529%2529&version=8.18.0.13) produces #f during the creation of a sandbox evaluator, this parameter is forced to #f during initialization of the sandbox. The default value of the parameter is #t.

Various aspects of the library change when the GUI library is available, such as using a new eventspace for each evaluator.

> ```
(sandbox-override-collection-paths)	→
(-> listof path-string?)
(sandbox-override-collection-paths paths) → void?
    paths	:
(-> listof path-string?)
```
(sandbox-security-guard)	→
(-> or/c security-guard? (→ security-guard?))
(sandbox-security-guard guard) → void?
    guard	:
(-> or/c security-guard? (→ security-guard?))```


# 14.12 Sandboxed Evaluation
A [parameter](eval-model.html#%28tech._parameter%29) that determines the initial ([current-security-guard](securityguards.html#%28def._%28%28quote._~23~25kernel%29._current-security-guard%29%29)) for sandboxed evaluations. It can be either a security guard, or a function to construct one. The default is a function that restricts the access of the current security guard by forbidding all filesystem I/O except for specifications in [sandbox-path-permissions](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-path-permissions%29%29), and it uses [sandbox-network-guard](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-network-guard%29%29) for network connections.
> ```
(sandbox-path-permissions)	→
(-> listof (list/c (or/c ' execute ' write ' delete
    ' read-bytecode ' read ' exists)
    (or/c byte-regexp? bytes? string? path?)))
(sandbox-path-permissions perms) → void?
    perms	:
(-> listof (list/c (or/c ' execute ' write ' delete
    ' read-bytecode ' read ' exists)
    (or/c byte-regexp? bytes? string? path?)))


# 14.12 Sandboxed Evaluation
```
(sandbox-network-guard)	→
(-> symbol?
    (or/c (and/c string? immutable?) #f)
    (or/c (integer-in 1 65535) #f)
    (or/c ' server ' client)
    . → . any)
(sandbox-network-guard proc) → void?
    proc	:
(-> symbol?
    (or/c (and/c string? immutable?) #f)
    (or/c (integer-in 1 65535) #f)
    (or/c ' server ' client)
    . → . any)```

A [parameter](eval-model.html#%28tech._parameter%29) that specifies a procedure to be used (as is) by the default [sandbox-security-guard](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-security-guard%29%29). The default forbids all network connection.

> ```
(sandbox-exit-handler)	→
(-> any/c . → . any)
(sandbox-exit-handler handler) → void?
    handler	:
(-> any/c . → . any)
```
(exit-handler)	→
(-> or/c (>=/c 0) #f)```
A [parameter](eval-model.html#%28tech._parameter%29) that determines the total memory limit on the sandbox in megabytes (it can hold a rational or a floating point number). When this limit is exceeded, the sandbox is terminated. This value is used when the sandbox is created and the limit cannot be changed afterwards. It defaults to 30mb. See [sandbox-eval-limits](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-eval-limits%29%29) for per-evaluation limits and a description of how the two limits work together.


# 14.12 Sandboxed Evaluation
Note that (when memory accounting is enabled) memory is attributed to the highest custodian that refers to it. This means that if you inspect a value that sandboxed evaluation returns outside of the sandbox, your own custodian will be charged for it. To ensure that it is charged back to the sandbox, you should remove references to such values when the code is done inspecting it.
This policy has an impact on how the sandbox memory limit interacts with the per-expression limit specified by [sandbox-eval-limits](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-eval-limits%29%29): values that are reachable from the sandbox, as well as from the interaction will count against the sandbox limit. For example, in the last interaction of this code,
> ```racket
> ( define e ( make-evaluator ' racket/base ) )
> ( e ' ( define a 1 ) )
> ( e ' ( for ( [ i ( in-range 20 ) ] ) ( set! a ( cons ( make-bytes 500000 ) a ) ) ) )
> ```
the memory blocks are allocated within the interaction limit, but since they’re chained to the defined variable, they’re also reachable from the sandbox — so they will count against the sandbox memory limit but not against the interaction limit (more precisely, no more than one block counts against the interaction limit).
> ```
(sandbox-eval-limits)	→
(-> or/c (list/c (or/c (>=/c 0) #f)
    (or/c (>=/c 0) #f))
    #f)
(sandbox-eval-limits limits) → void?
    limits	:
(-> or/c (list/c (or/c (>=/c 0) #f)
    (or/c (>=/c 0) #f))
    #f)


# 14.12 Sandboxed Evaluation
```
(sandbox-eval-handlers)	→
(-> list/c (or/c #f ((→ any) . → . any))
    (or/c #f ((→ any) . → . any)))
(sandbox-eval-handlers handlers) → void?
    handlers	:
(-> list/c (or/c #f ((→ any) . → . any))
    (or/c #f ((→ any) . → . any)))```

A [parameter](eval-model.html#%28tech._parameter%29) that determines two (optional) handlers that wrap sandboxed evaluations. The first one is used when evaluating the initial program when the sandbox is being set-up, and the second is used for each interaction. Each of these handlers should expect a thunk as an argument, and they should execute these thunks — possibly imposing further restrictions. The default values are #f and [call-with-custodian-shutdown](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-custodian-shutdown%29%29), meaning no additional restrictions on initial sandbox code (e.g., it can start background threads), and a custodian-shutdown around each interaction that follows. Another useful function for this is [call-with-killing-threads](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-killing-threads%29%29) which kills all threads, but leaves other resources intact.

> ```
(sandbox-run-submodules)	→
(-> list/c symbol?)
(sandbox-run-submodules submod-syms) → void?
    submod-syms	:
(-> list/c symbol?)
```
(sandbox-make-inspector)	→
(-> inspector?)
(sandbox-make-inspector make) → void?
    make	:
(-> inspector?)```


# 14.12 Sandboxed Evaluation
A [parameter](eval-model.html#%28tech._parameter%29) that determines the (nullary) procedure that is used to create the inspector for sandboxed evaluation. The procedure is called when initializing an evaluator. The default parameter value is ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) () ([make-inspector](inspectors.html#%28def._%28%28quote._~23~25kernel%29._make-inspector%29%29) ([current-inspector](inspectors.html#%28def._%28%28quote._~23~25kernel%29._current-inspector%29%29)))).
> ```
(sandbox-make-code-inspector)	→
(-> inspector?)
(sandbox-make-code-inspector make) → void?
    make	:
(-> inspector?)
```
(nullary)	→
(-> logger?)```

A [parameter](eval-model.html#%28tech._parameter%29) that determines the procedure used to create the logger for sandboxed evaluation. The procedure is called when initializing an evaluator, and the default parameter value is [current-logger](logging.html#%28def._%28%28quote._~23~25kernel%29._current-logger%29%29). This means that it is not creating a new logger (this might change in the future).

> ```
(sandbox-make-plumber)	→
(-> or/c (→ plumber?) 'propagate)
(sandbox-make-plumber make) → void?
    make	:
(-> or/c (→ plumber?) 'propagate)
```
(sandbox-make-environment-variables)	→
(-> environment-variables?)
(sandbox-make-environment-variables make) → void?
    make	:
(-> environment-variables?)```


# 14.12 Sandboxed Evaluation
A [parameter](eval-model.html#%28tech._parameter%29) that determines the procedure used to create the [environment variable set](envvars.html#%28tech._environment._variable._set%29) for sandboxed evaluation. The procedure is called when initializing an evaluator, and the default parameter value constructs a new [environment variable set](envvars.html#%28tech._environment._variable._set%29) using ([environment-variables-copy](envvars.html#%28def._%28%28quote._~23~25kernel%29._environment-variables-copy%29%29) ([current-environment-variables](envvars.html#%28def._%28%28quote._~23~25kernel%29._current-environment-variables%29%29))).
> ```
(default-language-readers lang)  →  (listof module-path?)
  lang : module-path?
```

Creates a default list of readers that should be allowed to produce a module that uses lang as the language.

This default list includes the following (and more paths may be added in the future):

-   \`(submod ,lang reader)

-   ’lang/lang/reader if lang is a symbol

-   the module path producing by adding the relative path "lang/reader.rkt" to lang if lang is not a symbol

-   '(submod at-exp reader)

-   'at-exp/lang/reader

Added in version 1.2 of package sandbox-lib.

#### 14.12.3 Interacting with Evaluators

The following functions are used to interact with a sandboxed evaluator in addition to using it to evaluate code.

> ```
(evaluator-alive? evaluator)  →  boolean?
  evaluator : (any/c .  →  . any)
```
Determines whether the evaluator is still alive.
> ```
(parameter)	→
(-> any/c . → . any)


# 14.12 Sandboxed Evaluation
```
(parameter)	→
(-> any/c . → . any)```

Sends a break to the running evaluator. The effect of this is as if Ctrl-C was typed when the evaluator is currently executing, which propagates the break to the evaluator’s context.

> ```
(parameter)	→
(-> any/c . → . any)
```
(current-custodian)	→
(-> any/c . → . any)```
Changes the per-expression limits that evaluator uses to secs seconds of [shallow time](#%28tech._shallow._time%29) and mb megabytes (either one can be #f, indicating no limit).
This procedure should be used to modify an existing evaluator limits, because changing the [sandbox-eval-limits](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-eval-limits%29%29) parameter does not affect existing evaluators. See also [call-with-limits](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-limits%29%29).
> ```
(parameter)	→
(-> any/c . → . any)
```
(parameter)	→
(-> any)```

These functions are useful for use as an evaluation handler. [call-with-custodian-shutdown](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-custodian-shutdown%29%29) will execute the thunk in a fresh custodian, then shutdown that custodian, making sure that thunk could not have left behind any resources. [call-with-killing-threads](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-killing-threads%29%29) is similar, except that it kills threads that were left, but leaves other resources as is.

> ```
(parameter)	→
(-> any/c . → . any)
```


# 14.12 Sandboxed Evaluation
If (sandbox-input) is 'pipe when an evaluator is created, then this procedure can be used to retrieve the output port end of the pipe (when used with no arguments), or to add a string or a byte string into the pipe. It can also be used with eof, which closes the pipe.
> ```
(get-output evaluator)   →   (or/c #f input-port? bytes? string?)
  evaluator : (any/c .  →  . any)
(get-error-output evaluator)
   →   (or/c #f input-port? bytes? string?)
  evaluator : (any/c .  →  . any)```
Returns the output or error-output of the evaluator, in a way that depends on the setting of ([sandbox-output](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-output%29%29)) or ([sandbox-error-output](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-error-output%29%29)) when the evaluator was created:
-   if it was 'pipe, then [get-output](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._get-output%29%29) returns the input port end of the created pipe;
-   if it was 'bytes or 'string, then the result is the accumulated output, and the output port is reset so each call returns a different piece of the evaluator’s output (note that results are available only until the evaluator has terminated, and any allocations of the output are subject to the sandbox memory limit);
-   otherwise, it returns #f.
> ```
(get-uncovered-expressions evaluator
   [ prog?
    src)    →    (listof syntax?)
  evaluator : (any/c .  →  . any)
  prog? : any/c = #t
  src : any/c = default-src


# 14.12 Sandboxed Evaluation
```
Retrieves uncovered expression from an evaluator, as longs as the sandbox-coverage-enabled parameter had a true value when the evaluator was created. Otherwise, an exception is raised to indicate that no coverage information is available.

The prog? argument specifies whether to obtain expressions that were uncovered after only the original input program was evaluated (#t) or after all later uses of the evaluator (#f). Using #t retrieves a list that is saved after the input program is evaluated, and before the evaluator is used, so the result is always the same.

A #t value of prog? is useful for testing student programs to find out whether a submission has sufficient test coverage built in. A #f value is useful for writing test suites for a program to ensure that your tests cover the whole code.

The second optional argument, src, specifies that the result should be filtered to hold only syntax objects whose source matches src. The default is the source that was used in the program code, if there was one. Note that 'program is used as the source value if the input program was given as S-expressions or as a string (and in these cases it will be the default for filtering). If given #f, the result is the unfiltered list of expressions.

The resulting list of syntax objects has at most one expression for each position and span. Thus, the contents may be unreliable, but the position information is reliable (i.e., it always indicates source code that would be painted red in DrRacket when coverage information is used).

Note that if the input program is a sequence of syntax values, either make sure that they have 'program as the source field, or use the src argument. Using a sequence of S-expressions (not syntax objects) for an input program leads to unreliable coverage results, since each expression may be assigned a single source location.

> ```
(call-in-sandbox-context evaluator
    thunk
   [ unrestricted?)    →    any

  evaluator : (any/c .  →  . any)
  thunk : (  →   any)
  unrestricted? : boolean? = #f```

Calls the given thunk in the context of a sandboxed evaluator. The call is performed under the resource limits and evaluation handler that are used for evaluating expressions, unless unrestricted? is specified as true.

This process is usually similar to (evaluator ([list](pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29) thunk)), except that it does not rely on the common meaning of a sexpr-based syntax with list expressions as function application (which is not true in all languages). Note that this is more useful for meta-level operations such as namespace manipulation, it is not intended to be used as a safe-evaluation replacement (i.e., using the sandbox evaluator as usual).

In addition, you can avoid some of the sandboxed restrictions by using your own permissions, for example,

> ```racket
> ( let ( [ guard ( current-security-guard ) ] )
> ( call-in-sandbox-context
> ev
> ( lambda ( )
> ( parameterize ( [ current-security-guard guard ] )
> ; can access anything you want here
> ( delete-file "/some/file" ) ) ) ) )
> ```

#### 14.12.4 Miscellaneous

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>value</p>

<p>[gui?](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._gui~3f%29%29) : [boolean?](booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29)</p></blockquote></td></tr></tbody></table>

For backward compatibility, only: the result of [gui-available?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=gui&rel=Dynamic_Loading.html%23%2528def._%2528%2528lib._racket%252Fgui%252Fdynamic..rkt%2529._gui-available%7E3f%2529%2529&version=8.18.0.13) at the time that [racket/sandbox]() was instantiated.

The value of [gui?](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._gui~3f%29%29) is no longer used by [racket/sandbox]() itself. Instead, [gui-available?](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=gui&rel=Dynamic_Loading.html%23%2528def._%2528%2528lib._racket%252Fgui%252Fdynamic..rkt%2529._gui-available%7E3f%2529%2529&version=8.18.0.13) and [sandbox-gui-available](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._sandbox-gui-available%29%29) are checked at the time that a sandbox evaluator is created.

> ```
(call-with-limits secs mb thunk)  →  any
  secs : (or/c exact-nonnegative-integer? #f)
  mb : (or/c exact-nonnegative-integer? #f)
  thunk : (  →   any)
```


# 14.12 Sandboxed Evaluation
Executes the given thunk with memory and time restrictions: if execution consumes more than mb megabytes or more than secs shallow time seconds, then the computation is aborted and an exception recognizable by exn:fail:resource? is raised. Otherwise, the result of the thunk is returned as usual (a value, multiple values, or an exception). Each of the two limits can be #f to indicate the absence of a limit. See also custodian-limit-memory for information on memory limits.
To enforce limits, thunk is run in a new thread. As usual, the new thread starts with the same parameter values as the one that calls call-with-limits. Not as usual, parameter values from the thread used to run thunk are copied back to the thread that called call-with-limits when thunk completes.
Sandboxed evaluators use call-with-limits, according to the sandbox-eval-limits setting and uses of set-eval-limits: each expression evaluation is protected from timeouts and memory problems. Use call-with-limits directly only to limit a whole testing session, instead of each expression.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

(with-limits sec-expr mb-expr body ...)

A macro version of call-with-limits.
> ```
(call-with-deep-time-limit secs thunk) → any
  secs : exact-nonnegative-integer?
  thunk : (  →   any)```
Executes the given thunk with [deep time](#%28tech._deep._time%29) restrictions, and returns the values produced by thunk.


# 14.12 Sandboxed Evaluation
The given thunk is run in a new thread. If it errors or if the thread terminates returning a value, then ([values](values.html#%28def._%28%28quote._~23~25kernel%29._values%29%29)) is returned.
Changed in version 1.1 of package sandbox-lib: Changed to return thunk’s result if it completes normally.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([with-deep-time-limit](#%28form._%28%28lib._racket%2Fsandbox..rkt%29._with-deep-time-limit%29%29) secs-expr body ...)

A macro version of [call-with-deep-time-limit](#%28def._%28%28lib._racket%2Fsandbox..rkt%29._call-with-deep-time-limit%29%29).
> ```
(exn:fail:resource? v)  →  boolean?
  v : any/c
(exn:fail:resource-resource exn)
  →  (or/c 'time 'memory 'deep-time)
  exn : exn:fail:resource?


# 14.12 Sandboxed Evaluation
```
A predicate and accessor for exceptions that are raised by call-with-limits. The resource field holds a symbol, representing the resource that was expended. 'time is used for shallow time and 'deep-time is used for deep time.

------------------------------------------------------------------------

# 14.13 The racket/repl Library

### 14.13 The [racket/repl]() Library

|  |  |
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require [racket/repl]()) |  package: base |

The [racket/repl]() provides the same read-eval-print-loop binding as racket/base, but with even fewer internal dependencies than racket/base. It is loaded in some situations on startup, as described in Initialization.

------------------------------------------------------------------------

# 14.14 Linklets and the Core Compiler

### 14.14 Linklets and the Core Compiler

|  |  |
|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require [racket/linklet]()) |  package: base |

A linklet is a primitive element of compilation, bytecode marshaling, and evaluation. Racket’s implementations of modules, macros, and top-level evaluation are all built on linklets. Racket programmers generally do not encounter linklets directly, but the [racket/linklet]() library provides access to linklet facilities.

A single Racket module (or collection of top-level forms) is typically implemented by multiple linklets. For example, each phase of evaluation that exists in a module is implemented in a separate linklet. A linklet is also used for metadata such as the module path indexes for a module’s requires. These linklets, plus some other metadata, are combined to form a linklet bundle. Information in a linklet bundle is keyed by either a symbol or a fixnum. A linklet bundle containing linklets can be marshaled to and from a byte stream by write and (with read-accept-compiled is enabled) read.

When a Racket module has submodules, the linklet bundles for the module and the submodules are grouped together in a linklet directory. A linklet directory can have nested linklet directories. Information in a linklet directory is keyed by #f or a symbol, where #f must be mapped to a linklet bundle (if anything) and each symbol must be mapped to a linklet directory. A linklet directory can be equivalently viewed as a mapping from a lists of symbols to a linklet bundle. Like linklet bundles, a linklet directory can be marshaled to and from a byte stream by write and read; the marshaled form allows individual linklet bundles to be loaded independently.

A linklet consists of a set of variable definitions and expressions, an exported subset of the defined variable names, a set of variables to export from the linklet despite having no corresponding definition, and a set of imports that provide other variables for the linklet to use. To run a linklet, it is instantiated as as linklet instance (or just instance, for short). When a linklet is instantiated, it receives other linklet instances for its imports, and it extracts a specified set of variables that are exported from each of the given instances. The newly created linklet instance provides its exported variables for use by other linklets or for direct access via instance-variable-value. A linklet instance can be synthesized directly with make-instance.

A linklet is created by compiling an enriched S-expression representation of its source. Since linklets exist below the layer of macros and syntax objects, linklet compilation does not use syntax objects. Instead, linklet compilation uses correlated objects, which are like syntax objects without lexical-context information and without the constraint that content is coerced to correlated objects. Using an S-expression or correlated object, the grammar of a linklet as recognized by compile-linklet is

> > ```
(linklet [[imported-id/renamed ...] ...]
> > [ exported-id/renamed ... ]
> > defn-or-expr ... )

imported-id/renamed   =   imported-id
    |   (external-imported-id internal-imported-id)

exported-id/renamed   =   exported-id
    |   (internal-exported-id external-exported-id)```

Each import set \[imported-id/renamed [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)\] refers to a single imported instance, and each import-id/renamed corresponds to a variable from that instance. If separate external-imported-id and internal-imported-id are specified, then external-imported-id is the name of the variable as exported by the instance, and internal-imported-id is the name used to refer to the variable in the defn-or-exprs. For exports, separate internal-exported-id and external-exported-id names corresponds to the variable name as exported as referenced in the defn-or-exprs, respectively.

The grammar of an defn-or-expr is similar to the expander’s grammar of fully expanded expressions (see [Fully Expanded Programs](syntax-model.html#%28part._fully-expanded%29)) with some exceptions: [quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) and [#%top](__top.html#%28form._%28%28quote._~23~25kernel%29._~23~25top%29%29) are not allowed; [#%plain-lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._~23~25plain-lambda%29%29) is spelled [lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29); [#%plain-app](application.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._~23~25plain-app%29%29) is omitted (i.e., application is implicit); [lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29), [case-lambda](lambda.html#%28form._%28%28quote._~23~25kernel%29._case-lambda%29%29), [let-values](let.html#%28form._%28%28quote._~23~25kernel%29._let-values%29%29), and [letrec-values](let.html#%28form._%28%28quote._~23~25kernel%29._letrec-values%29%29) can have only a single body expression; begin-unsafe is like [begin](begin.html#%28form._%28%28quote._~23~25kernel%29._begin%29%29) in an expression position, but its body is compiled in [unsafe mode](#%28tech._unsafe._mode%29); and numbers, booleans, strings, and byte strings are self-quoting. Primitives are accessed directly by name, and shadowing is not allowed within a linklet form for primitive names (see [linklet-body-reserved-symbol?](#%28def._%28%28lib._racket%2Flinklet..rkt%29._linklet-body-reserved-symbol~3f%29%29)), imported variables, defined variables, or local variables.

When an exported-id/renamed has no corresponding definition among the defn-or-exprs, then the variable is effectively defined as uninitialized; referencing the variable will trigger [exn:fail:contract:variable](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3avariable%29%29), the same as referencing a variable before it is defined. When a target instance is provided to [instantiate-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._instantiate-linklet%29%29), any existing variable with the same name will be left as-is, instead of set to undefined. This treatment of uninitialized variables provides core support for top-level evaluation where variables may be referenced and then defined in a separate element of compilation.

Added in version 6.90.0.1 of package base.

> ```
(linklet? v)  →  boolean?
  v : any/c
```


# 14.12 Sandboxed Evaluation
Returns #t if v is a linklet, #f otherwise.
> ```
(compile-linklet form
   [ info
    import-keys
    get-import
    options)    →    linklet?
  form : (or/c correlated? any/c)
  info : (or/c hash? any/c) = #f
  import-keys : #f = #f
  get-import : #f = #f
   options   :   ( listof ( or/c ' serializable ' unsafe ' static ' quick
> ' use-prompt ' unlimited-compile
> ' uninterned-literal ) )
      =   '(serializable)
(compile-linklet   form
    info
    import-keys
   [ get-import
    options)    →    linklet?   vector?
  form : (or/c correlated? any/c)
  info : (or/c hash? any/c)
  import-keys : vector?
   get-import   :   ( or/c #f ( any/c .  →  . ( values ( or/c linklet? instance? #f )
> ( or/c vector? #f ) ) ) )
      =   #f
   options   :   ( listof ( or/c ' serializable ' unsafe ' static ' quick
> ' use-prompt ' unlimited-compile
> ' uninterned-literal ) )
      =   '(serializable)```
Takes an S-expression or [correlated object](#%28tech._correlated._object%29) for a linklet form and produces a [linklet](#%28tech._linklet%29). As long as 'serializable included in options, the resulting linklet can be marshaled to and from a byte stream when it is part of a [linklet bundle](#%28tech._linklet._bundle%29) (possibly in a [linklet directory](#%28tech._linklet._directory%29)).


# 14.12 Sandboxed Evaluation
The optional info hash provides various debugging details about the linklet, such as the module name the linklet is part of, the linklet name, and the phase for body linklets. If a 'name value is present in the hash, it is associated to the linklet for debugging purposes and as the default name of the linklet’s instance. If info is not a hash, it is assumed to be a name value directly for backward compatibility.
The optional import-keys and get-import arguments support cross-linklet optimization. If import-keys is a vector, it must have as many elements as sets of imports in form. If the compiler becomes interested in optimizing a reference to an imported variable, it passes back to get-import (if non-#f) the element of import-keys that corresponds to the variable’s import set. The get-import function can then return a linklet or instance that represents an instance to be provided to the compiled linklet when it is eventually instantiated; ensuring consistency between reported linklet or instance and the eventual instance is up to the caller of [compile-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._compile-linklet%29%29), but see also [linklet-add-target-machine-info](#%28def._%28%28lib._racket%2Flinklet..rkt%29._linklet-add-target-machine-info%29%29). If get-import returns #f as its first value, the compiler will be prevented from making any assumptions about the imported instance. The second result from get-import is an optional vector of keys to provide transitive information on a returned linklet’s imports (and is not allowed for a returned instance); the returned vector must have the same number of elements as the linklet has imports. When vector elements are [eq?](Equality.html#%28def._%28%28quote._~23~25kernel%29._eq~3f%29%29) and non-#f, the compiler can assume that they correspond to the same run-time instance. A #f value for get-import is equivalent to a function that always returns two #f results.


# 14.12 Sandboxed Evaluation
When import-keys is not #f, then the compiler is allowed to grow or shrink the set of imported instances for the linklet. The result vector specifies the keys of the imports for the returned linklet. Any key that is #f or a [linklet instance](#%28tech._linklet._instance%29) must be preserved intact, however.
If 'unsafe is included in options, then the linklet is compiled in unsafe mode: uses of safe operations within the linklet can be converted to unsafe operations on the assumption that the relevant contracts are satisfied. For example, [car](pairs.html#%28def._%28%28quote._~23~25kernel%29._car%29%29) is converted to [unsafe-car](unsafe.html#%28def._%28%28lib._racket%2Funsafe%2Fops..rkt%29._unsafe-car%29%29). Some substituted unsafe operations may not have directly accessible names, such as the unsafe variant of [in-list](sequences.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-list%29%29) that can be substituted in [unsafe mode](#%28tech._unsafe._mode%29). An unsafe operation is substituted only if its (unchecked) contract is subsumed by the safe operation’s contract. The fact that the linklet is compiled in [unsafe mode](#%28tech._unsafe._mode%29) can be exposed through [variable-reference-from-unsafe?](Namespaces.html#%28def._%28%28quote._~23~25kernel%29._variable-reference-from-unsafe~3f%29%29) using a variable reference produced by a [#%variable-reference](Locations____variable-reference.html#%28form._%28%28quote._~23~25kernel%29._~23~25variable-reference%29%29) form within the module body. Within a linklet an individual expression can be compiled in unsafe mode by wrapping it in begin-unsafe; when a whole linklet is compiled in unsafe mode, begin-unsafe is redundant and ignored.


# 14.12 Sandboxed Evaluation
If 'static is included in options, then the linklet must be instantiated only once; if the linklet is serialized, then any individual instance read from the serialized form must be instantiated at most once. Compilation with 'static is intended to improve the performance of references within the linklet to defined and imported variables.
If 'quick is included in options, then linklet compilation may trade run-time performance for compile-time performance—that is, spend less time compiling the linklet, but the resulting linklet may run more slowly.
If 'use-prompt is included in options, then instantiating resulting linklet always wraps a prompt around each definition and immediate expression in the linklet. Otherwise, supplying #t as the use-prompt? argument to [instantiate-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._instantiate-linklet%29%29) may only wrap a prompt around the entire instantiation.
If 'unlimited-compile is included in options, then compilation never falls back to interpreted mode for an especially large linklet. See also [CS Compilation Modes](compiler.html#%28part._cs-compiler-modes%29).


# 14.12 Sandboxed Evaluation
If 'uninterned-literal is included in options, then literals in form will not necessarily be interned via [datum-intern-literal](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-intern-literal%29%29) when compiling or loading the linklet. Disabling the use of [datum-intern-literal](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-intern-literal%29%29) can be especially useful of the linklet includes a large string or byte string constant that is not meant to be shared.
The symbols in options must be distinct, otherwise [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
Changed in version 7.1.0.8 of package base: Added the 'use-prompt option.
Changed in version 7.1.0.10: Added the 'uninterned-literal option.
Changed in version 7.5.0.14: Added the 'quick option.
Changed in version 8.11.1.2: Changed info to a hash.
Changed in version 8.13.0.9: Added the 'unlimited-compile option.
> ```
(recompile-linklet linklet
   [ info
    import-keys
    get-import
    options)    →    linklet?
  linklet : linklet?
  info : (or/c hash? any/c) = #f
  import-keys : #f = #f
  get-import : #f = #f
   options   :   ( listof ( or/c ' serializable ' unsafe ' static ' quick
> ' use-prompt ' uninterned-literal ) )
      =   '(serializable)
(recompile-linklet   linklet
    info
    import-keys
   [ get-import
    options)    →    linklet?   vector?


# 14.12 Sandboxed Evaluation
  linklet : linklet?
  info : (or/c hash? any/c)
  import-keys : vector?
   get-import   :   ( or/c ( any/c .  →  . ( values ( or/c linklet? #f )
> ( or/c vector? #f ) ) )
> #f )
      =   (lambda (import-key) (values #f #f))
   options   :   ( listof ( or/c ' serializable ' unsafe ' static ' quick
> ' use-prompt ' uninterned-literal ) )
      =   '(serializable)
```
Like compile-linklet, but takes an already-compiled linklet and potentially optimizes it further.

Changed in version 7.1.0.6 of package base: Added the options argument.
Changed in version 7.1.0.8: Added the 'use-prompt option.
Changed in version 7.1.0.10: Added the 'uninterned-literal option.
Changed in version 7.5.0.14: Added the 'quick option.
Changed in version 8.11.1.2: Changed info to a hash.

> ```
(eval-linklet linklet)   →   linklet?
  linklet : linklet?```

Returns a variant of a linklet that is prepared for JIT compilation such that every later use of the result linklet with [instantiate-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._instantiate-linklet%29%29) shares the JIT-generated code. However, the result of [eval-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._eval-linklet%29%29) cannot be marshaled to a byte stream as part of a [linklet bundle](#%28tech._linklet._bundle%29), and it cannot be used with [recompile-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._recompile-linklet%29%29).

> ```
(instantiate-linklet linklet
    import-instances
   [ target-instance?
    use-prompt?)    →    instance?

  linklet : linklet?
  import-instances : (listof instance?)
  target-instance? : #f = #f
  use-prompt? : any/c = #t
(instantiate-linklet   linklet
    import-instances
    target-instance
   [ use-prompt?)    →    any

  linklet : linklet?
  import-instances : (listof instance?)
  target-instance : instance?
  use-prompt? : any/c = #t
```


# 14.12 Sandboxed Evaluation
(parameter)	→
(-> listof (listof symbol?))```
Returns a description of a linklet’s imports. Each element of the result list corresponds to an import set as satisfied by a single instance on instantiation, and each member of the set is a variable name that is used from the corresponding imported instance.
> ```
(parameter)	→
(-> listof symbol?)
```

Returns a description of a linklet’s exports. Each element of the list corresponds to a variable that is made available by the linklet in its instance.

> ```
(linklet-add-target-machine-info   linklet
    from-linklet)    →    linklet?

  linklet : linklet?
  from-linklet : (or linklet? hash?)
```


# 14.12 Sandboxed Evaluation
When [compile-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._compile-linklet%29%29) or [recompile-linklet](#%28def._%28%28lib._racket%2Flinklet..rkt%29._recompile-linklet%29%29) requests a linklet via get-import for cross-module information, the linklet is expected to have information compatible with the current compilation target as determined by [current-compile-target-machine](eval.html#%28def._%28%28quote._~23~25kernel%29._current-compile-target-machine%29%29). To simplify the management of linklets to both run and use for cross-compilation, a linklet implementation may support information for multiple target machines within a linklet, in which case [linklet-add-target-machine-info](#%28def._%28%28lib._racket%2Flinklet..rkt%29._linklet-add-target-machine-info%29%29) returns a linklet like linklet but with target-specific information added from from-linklet. The two linklets must be from compatible sources, but [linklet-add-target-machine-info](#%28def._%28%28lib._racket%2Flinklet..rkt%29._linklet-add-target-machine-info%29%29) might perform only a sanity check for compatibility.
The from-linklet can be a linklet or a summary of a linklet’s information as produced by [linklet-summarize-target-machine-info](#%28def._%28%28lib._racket%2Flinklet..rkt%29._linklet-summarize-target-machine-info%29%29).
Added in version 8.12.0.3 of package base.
Changed in version 8.17.0.3: Added support for from-linklet as a summary.
> ```
(linklet-summarize-target-machine-info from-linklet)  →  hash?
  from-linklet : linklet?


# 14.12 Sandboxed Evaluation
```
Returns a value that has the same information as from-linklet for linklet-add-target-machine-info, but in a form that can be portably serialized via racket/fasl.

Added in version 8.17.0.3 of package base.

> ```
(linklet-directory? v)   →   boolean?
  v : any/c```

Returns #t if v is a [linklet directory](#%28tech._linklet._directory%29), #f otherwise.

> ```
(hash  →  linklet-directory content)  →  linklet-directory?
  content : (and/c hash? hash-eq? immutable? (not/c impersonator?))
```
Constructs a linklet directory given mappings in the form of a hash table. Each key of content must be either a symbol or #f, each symbol must be mapped to a linklet directory, and #f must be mapped to a linklet bundle or not mapped.
> ```
(linklet-directory  →  hash linklet-directory)
   →   (and/c hash? hash-eq? immutable? (not/c impersonator?))
  linklet-directory : linklet-directory?```
Extracts the content of a [linklet directory](#%28tech._linklet._directory%29) into a [hash table](hashtables.html#%28tech._hash._table%29).
> ```
(linklet-bundle? v)  →  boolean?
  v : any/c


# 14.12 Sandboxed Evaluation
```
Returns #t if v is a linklet bundle, #f otherwise.

> ```
(hash  →  linklet-bundle content)   →   linklet-bundle?
  content : (and/c hash? hash-eq? immutable? (not/c impersonator?))```

Constructs a [linklet bundle](#%28tech._linklet._bundle%29) given mappings in the form of a [hash table](hashtables.html#%28tech._hash._table%29). Each key of content must be either a symbol or a [fixnum](numbers.html#%28tech._fixnum%29). Values in the hash table are unconstrained, but the intent is that they are all [linklets](#%28tech._linklet%29) or values that can be recovered from [write](Writing.html#%28def._%28%28quote._~23~25kernel%29._write%29%29) output by [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29).

> ```
(linklet-bundle  →  hash linklet-bundle)
  →  (and/c hash? hash-eq? immutable? (not/c impersonator?))
  linklet-bundle : linklet-bundle?
```
(parameter)	→```
Return #t if sym is a primitive name or other identifier that is not allowed as a binding within a linklet, #f otherwise.
Added in version 8.2.0.1 of package base.
> ```
(instance? v)  →  boolean?
  v : any/c


# 14.12 Sandboxed Evaluation
```
(parameter)	→
(-> or/c #f 'constant 'consistent)```

Constructs a [linklet instance](#%28tech._linklet._instance%29) directly. Besides associating an arbitrary name and data value to the instance, the instance is populated with variables as specified by variable-name and variable-value.

The optional data and mode arguments must be provided if any variable-name and variable-value arguments are provided. The mode argument is used as in [instance-set-variable-value!](#%28def._%28%28lib._racket%2Flinklet..rkt%29._instance-set-variable-value%21%29%29) for every variable-name.

> ```
(instance-name instance)  →  any/c
  instance : instance?
```
Returns the value associated to instance as its name—either the first value provided to make-instance or the name of a linklet that was instantiated to create the instance.
> ```
(instance-data instance)   →   any/c
  instance : instance?```
Returns the value associated to instance as its data—either the second value provided to [make-instance](#%28def._%28%28lib._racket%2Flinklet..rkt%29._make-instance%29%29) or the default #f.
> ```
(parameter)	→
(-> list symbol?)
```
(parameter)	→
(-> lambda () (error ....))```

Returns the value of the variable exported as name from instance. If no such variable is exported, then fail-k is used in the same way as by [hash-ref](hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash-ref%29%29).

> ```
(parameter)	→
(-> or/c #f 'constant 'consistent)
```
(parameter)	→```


# 14.12 Sandboxed Evaluation
Changes instance so that it does not export a variable as name, as long as name does not exist as a constant variable. If a variable for name exists as constant, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
> ```
(parameter)	→
```
(parameter)	→
(-> if ref-site? (or/c instance? #f symbol?) instance?)```

Extracts the instance where the variable of varref is defined if ref-site? is #f, and returns the instance where varref itself resides if ref-site? is true. This notion of [variable reference](Locations____variable-reference.html#%28tech._variable._reference%29) is the same as at the module level and can reflect the linklet instance that implements a particular phase of a module instance.

When ref-site? is #f, the result is #f when varref is from ([#%variable-reference](Locations____variable-reference.html#%28form._%28%28quote._~23~25kernel%29._~23~25variable-reference%29%29)) with no identifier. The result is a symbol if varref refers to a primitive.

> ```
(correlated? v) → boolean?
  v : any/c

(correlated-source crlt)  →  any
  crlt : correlated?

(correlated-line crlt)  →  (or/c exact-positive-integer? #f)
  crlt : correlated?

(correlated-column crlt)  →  (or/c exact-nonnegative-integer? #f)
  crlt : correlated?

(correlated-position crlt)  →  (or/c exact-positive-integer? #f)
  crlt : correlated?

(correlated-span crlt)  →  (or/c exact-nonnegative-integer? #f)
  crlt : correlated?

(correlated-e crlt)  →  any
  crlt : correlated?

(correlated  →  datum crlt)  →  any
  crlt : (or/c correlated? any/c)

(datum  →  correlated v [srcloc prop)  →  correlated?
  v : any/c
   srcloc   :   ( or/c correlated? #f
> ( list/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) )
> ( vector/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) ) )
      =   #f

  prop : (or/c correlated? #f) = #f

(correlated-property crlt key val)  →  correlated?
  crlt : correlated?
  key : any/c
  val : any/c
(correlated-property crlt key)  →  any/c
  crlt : correlated?
  key : any/c

(correlated-property-symbol-keys crlt)  →  list?
  crlt : correlated?
```


# 14.12 Sandboxed Evaluation
Like syntax?, syntax-source, syntax-line, syntax-column, syntax-position, syntax-span, syntax-e, syntax  →  datum, datum  →  syntax, syntax-property, and syntax-property-symbol-keys, but for correlated objects.
Unlike datum  →  syntax, datum  →  correlated does not recur through the given S-expression and convert pieces to correlated objects. Instead, a correlated object is simply wrapped around the immediate value. In contrast, correlated  →  datum recurs through its argument (which is not necessarily a correlated object) to discover any correlated objects and convert them to plain S-expressions.
Changed in version 7.6.0.6 of package base: Added the prop argument to datum  →  correlated.
------------------------------------------------------------------------


# 14.15 Deprecation


### 14.15 Deprecation
|  |  |
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require [racket/deprecation]()) |  package: base |
The bindings documented in this section are provided by the [racket/deprecation]() library, not racket/base or racket.
A deprecated function, macro, or other API element is one that’s been formally declared obsolete, typically with an intended replacement that users should migrate to. The [racket/deprecation]() library provides a standardized mechanism for declaring deprecations in a machine-processable manner. These declarations can allow tools such as resyntax to automate migrating code away from deprecated APIs. Note that a dependency on the [racket/deprecation]() library does not imply a dependency on any such tools.


#### 14.15.1 Deprecated Aliases
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

(define-deprecated-alias alias-id target-id)

Binds alias-id as an alias of target-id with the intent that users of alias-id should prefer to use target-id instead. The given alias-id is bound as a deprecated alias transformer, which is a kind of rename transformer. The given target-id may be bound to a function, macro, or any other kind of binding.
Note that although alias-id is an alias of target-id, it is not considered the same binding as target-id and is not free-identifier=?. This is because the alias binding must be inspectable at compile-time with deprecated-alias? and deprecated-alias-target, and it must remain inspectable even if the alias is provided by a module. This requires a module providing the alias and the target to provide them as two distinct bindings: one which is bound to a deprecated alias transformer and one which isn’t.
Examples:
> ```racket
> > ( require racket/deprecation )
> > ( define a 42 )
> > ( define-deprecated-alias legacy-a a )
> > legacy-a
> 42
> ```


#### 14.15.2 Deprecated Alias Transformers
|  |  |
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require racket/deprecation/transformer) |  package: base |
The racket/deprecation/transformer module provides compile-time supporting code for the [racket/deprecation]() library, primarily for use in tools that wish to reflect on deprecated code.
A deprecated alias transformer is a kind of rename transformer which signals that the transformer binding is a deprecated alias of the target identifier. This signal is intended for consumption in tools such as editors (which may wish to display a warning when deprecated aliases are used) and automated refactoring systems (which may wish to replace deprecated aliases with their target identifiers automatically).
> ```
(deprecated-alias? v) → boolean?
  v : any/c```


# 14.15 Deprecation
Returns true if v is a [deprecated alias transformer](#%28tech._deprecated._alias._transformer%29) and returns false otherwise. Implies [rename-transformer?](stxtrans.html#%28def._%28%28quote._~23~25kernel%29._rename-transformer~3f%29%29). To determine if an identifier is bound to a deprecated alias transformer, use [syntax-local-value/immediate](stxtrans.html#%28def._%28%28quote._~23~25kernel%29._syntax-local-value%2Fimmediate%29%29) and then use [deprecated-alias?](#%28def._%28%28lib._racket%2Fdeprecation%2Ftransformer..rkt%29._deprecated-alias~3f%29%29) on the transformer value.
Examples:
> ```racket
> > ( require ( for-syntax racket/base racket/deprecation/transformer ) racket/deprecation syntax/parse/define )
> > ( define-syntax-parse-rule ( is-deprecated? id:id ) #:do [ ( define-values ( transformer _ ) ( syntax-local-value/immediate #' id ( λ ( ) ( values #false #false ) ) ) ) ] #:with result ( deprecated-alias? transformer ) ' result )
> > ( define-deprecated-alias bad-list list )
> > ( is-deprecated? list )
> #f
> > ( is-deprecated? bad-list )
> #t
> ```
> ```
(deprecated-alias target)  →  deprecated-alias?
  target : identifier?


# 14.15 Deprecation
```
Constructs a deprecated alias transformer which expands to target when used. The returned alias is a rename transformer and is thus suitable for use with define-syntax. When expanding, the usage of target is annotated with the 'not-free-identifier=? syntax property to ensure that the alias and the target are treated as distinct bindings, even when provided by a module.

This constructor is not intended for direct use by users who just want to declare a deprecated alias. Such users should prefer the define-deprecated-alias form instead.

> ```
(deprecated-alias-target alias) → identifier?
  alias : deprecated-alias?```

Returns the target identifier that alias expands to.

------------------------------------------------------------------------

# 15 Operating System

## 15 Operating System

|                                                                                |
|----------------------------------------------------------------------------------------------------------------------------------|
|     [15.1 Paths](pathutils.html)                                                                      |
|       [15.1.1 Manipulating Paths](Manipulating_Paths.html)                                            |
|       [15.1.2 More Path Utilities](More_Path_Utilities.html)                                          |
|       [15.1.3 Unix and Mac OS Paths](unixpaths.html)                                                  |
|         [15.1.3.1 Unix Path Representation](unixpaths.html#%28part._unixpathrep%29)                   |
|       [15.1.4 Windows Paths](windowspaths.html)                                                       |
|         [15.1.4.1 Windows Path Representation](windowspaths.html#%28part._windowspathrep%29)          |
|     [15.2 Filesystem](Filesystem.html)                                                                |
|       [15.2.1 Locating Paths](Filesystem.html#%28part._findpaths%29)                                  |
|       [15.2.2 Files](Filesystem.html#%28part._fileutils%29)                                           |
|       [15.2.3 Directories](Filesystem.html#%28part._directories%29)                                   |
|       [15.2.4 Detecting Filesystem Changes](Filesystem.html#%28part._filesystem-change%29)            |
|       [15.2.5 Declaring Paths Needed at Run Time](Filesystem.html#%28part._runtime-path%29)           |
|       [15.2.6 More File and Directory Utilities](Filesystem.html#%28part._file-lib%29)                |
|     [15.3 Networking](networking.html)                                                                |
|       [15.3.1 TCP](tcp.html)                                                                          |
|       [15.3.2 UDP](udp.html)                                                                          |
|     [15.4 Processes](subprocess.html)                                                                 |
|       [15.4.1 Simple Subprocesses](subprocess.html#%28part._.Simple_.Subprocesses%29)                 |
|     [15.5 Logging](logging.html)                                                                      |
|       [15.5.1 Creating Loggers](logging.html#%28part._.Creating_.Loggers%29)                          |
|       [15.5.2 Logging Events](logging.html#%28part._.Logging_.Events%29)                              |
|       [15.5.3 Receiving Logged Events](logging.html#%28part._receiving-logged-events%29)              |
|       [15.5.4 Additional Logging Functions](logging.html#%28part._.Additional_.Logging_.Functions%29) |
|     [15.6 Time](time.html)                                                                            |
|       [15.6.1 Date Utilities](time.html#%28part._date-string%29)                                      |
|     [15.7 Environment Variables](envvars.html)                                                        |
|     [15.8 Environment and Runtime Information](runtime.html)                                          |
|     [15.9 Command-Line Parsing](Command-Line_Parsing.html)                                            |
|     [15.10 Additional Operating System Functions](os-lib.html)                                        |

------------------------------------------------------------------------

# 15.1 Paths

### 15.1 Paths

When a Racket procedure takes a filesystem path as an argument, the path can be provided either as a string or as an instance of the path datatype. If a string is provided, it is converted to a path using [string->path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._string-~3epath%29%29). Beware that some paths may not be representable as strings; see [Unix Path Representation](unixpaths.html#%28part._unixpathrep%29) and [Windows Path Representation](windowspaths.html#%28part._windowspathrep%29) for more information. A Racket procedure that generates a filesystem path always generates a [path](#%28tech._path%29) value.

By default, paths are created and manipulated for the current platform, but procedures that merely manipulate paths (without using the filesystem) can manipulate paths using conventions for other supported platforms. The [bytes->path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._bytes-~3epath%29%29) procedure accepts an optional argument that indicates the platform for the path, either 'unix or 'windows. For other functions, such as [build-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29) or [simplify-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._simplify-path%29%29), the behavior is sensitive to the kind of path that is supplied. Unless otherwise specified, a procedure that requires a path accepts only paths for the current platform.

Two [path](#%28tech._path%29) values are [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29) when they use the same convention type and when their byte-string representations are [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29). A path string (or byte string) cannot be empty, and it cannot contain a nul character or byte. When an empty string or a string containing nul is provided as a path to any procedure except [absolute-path?](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._absolute-path~3f%29%29), [relative-path?](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._relative-path~3f%29%29), or [complete-path?](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29), the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

Most Racket primitives that accept paths first cleanse the path before using it. Procedures that build paths or merely check the form of a path do not cleanse paths, with the exceptions of [cleanse-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._cleanse-path%29%29), [expand-user-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._expand-user-path%29%29), and [simplify-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._simplify-path%29%29). For more information about path cleansing and other platform-specific details, see [Unix and Mac OS Paths](unixpaths.html) and [Windows Paths](windowspaths.html).

------------------------------------------------------------------------

# 15.1.1 Manipulating Paths

#### 15.1.1 Manipulating Paths

> ```
(path? v)  →  boolean?
  v : any/c
```


# 14.15 Deprecation
Returns #t if v is a path value for the current platform (not a string, and not a path for a different platform), #f otherwise.
> ```
(path-string? v)  →  boolean?
  v : any/c
```

Returns #t if v is either a path or string: either a path for the current platform or a non-empty string without nul characters. Returns #f otherwise.

> ```
(path-for-some-system? v)  →  boolean?
  v : any/c
```
Returns #t if v is a path value for some platform (not a string), #f otherwise.
> ```
(string  →  path str)  →  path?
  str : string?
```

Produces a path whose byte-string encoding is ([string->bytes/locale](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._string-~3ebytes%2Flocale%29%29) str ([char->integer](characters.html#%28def._%28%28quote._~23~25kernel%29._char-~3einteger%29%29) #\\?)) on Unix and Mac OS or ([string->bytes/utf-8](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._string-~3ebytes%2Futf-8%29%29) str) on Windows.

Beware that the current locale might not encode every string, in which case [string->path](#%28def._%28%28quote._~23~25kernel%29._string-~3epath%29%29) can produce the same path for different strs. See also [string->path-element](#%28def._%28%28quote._~23~25kernel%29._string-~3epath-element%29%29), which should be used instead of [string->path](#%28def._%28%28quote._~23~25kernel%29._string-~3epath%29%29) when a string represents a single [path element](More_Path_Utilities.html#%28tech._path._element%29). For information on how strings and byte strings encode paths, see [Unix Path Representation](unixpaths.html#%28part._unixpathrep%29) and [Windows Path Representation](windowspaths.html#%28part._windowspathrep%29).

See also [string->some-system-path](More_Path_Utilities.html#%28def._%28%28lib._racket%2Fpath..rkt%29._string-~3esome-system-path%29%29), and see [Unix Path Representation](unixpaths.html#%28part._unixpathrep%29) and [Windows Path Representation](windowspaths.html#%28part._windowspathrep%29) for information on how strings encode paths.

Changed in version 6.1.1.1 of package base: Changed Windows conversion to always use UTF-8.

> ```
(bytes → path bstr [type) → path?
  bstr : bytes?
  type : (or/c 'unix 'windows) = (system-path-convention-type)
```


# 14.15 Deprecation
Produces a path (for some platform) whose byte-string encoding is bstr, where bstr must not contain a nul byte. The optional type specifies the convention to use for the path.
For converting relative path elements from literals, use instead bytes  →  path-element, which applies a suitable encoding for individual elements.
For information on how byte strings encode paths, see Unix Path Representation and Windows Path Representation.
> ```
(path  →  string path)   →   string?
  path : path?```
Produces a string that represents path by decoding path’s byte-string encoding using the current locale on Unix and Mac OS and by using UTF-8 on Windows. In the former case, ? is used in the result string where encoding fails, and if the encoding result is the empty string, then the result is "?".
The resulting string is suitable for displaying to a user, string-ordering comparisons, etc., but it is not suitable for re-creating a path (possibly modified) via [string->path](#%28def._%28%28quote._~23~25kernel%29._string-~3epath%29%29), since decoding and re-encoding the path’s byte string may lose information.
Furthermore, for display and sorting based on individual [path elements](More_Path_Utilities.html#%28tech._path._element%29) (such as pathless file names), use [path-element->string](#%28def._%28%28quote._~23~25kernel%29._path-element-~3estring%29%29), instead, to avoid special encodings use to represent some relative paths. See [Windows Paths](windowspaths.html) for specific information about the conversion of Windows paths.


# 14.15 Deprecation
See also [some-system-path->string](More_Path_Utilities.html#%28def._%28%28lib._racket%2Fpath..rkt%29._some-system-path-~3estring%29%29).
Changed in version 6.1.1.1 of package base: Changed Windows conversion to always use UTF-8.
> ```
(path  →  bytes path)  →  bytes?
  path : path-for-some-system?
```
Produces path’s byte-string representation. No information is lost in this translation, so that (bytes  →  path (path  →  bytes path) (path-convention-type path)) always produces a path that is equal? to path. The path argument can be a path for any platform.

Conversion to and from byte values is useful for marshaling and unmarshaling paths, but manipulating the byte form of a path is generally a mistake. In particular, the byte string may start with a \\\\?\\REL encoding for Windows paths. Instead of path  →  bytes, use split-path and path-element  →  bytes to manipulate individual path elements.

For information on how byte strings encode paths, see Unix Path Representation and Windows Path Representation.

> ```
(string → path-element str
   [ false-on-non-element?)

   →   (or/c (and/c path? path-element?) #f)
  str : string?
  false-on-non-element? : any/c = #f```

Like [string->path](#%28def._%28%28quote._~23~25kernel%29._string-~3epath%29%29), except that str corresponds to a single relative element in a path, and it is encoded as necessary to convert it to a path. See [Unix and Mac OS Paths](unixpaths.html) and [Windows Paths](windowspaths.html) for more information on the conversion of paths.

If str does not correspond to any [path element](More_Path_Utilities.html#%28tech._path._element%29) (e.g., it is an absolute path, or it can be split), or if it corresponds to an up-directory or same-directory indicator on Unix and Mac OS, then either #f is returned or [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised. A #f is returned only when false-on-non-element? is true.

Like [path->string](#%28def._%28%28quote._~23~25kernel%29._path-~3estring%29%29), information can be lost from str in the locale-specific conversion to a path.

Changed in version 8.1.0.6 of package base: Added the false-on-non-element? argument.

> ```
(bytes → path-element bstr
   [ type
    false-on-non-element?)

  →  (or/c path-element? #f)
  bstr : bytes?
  type : (or/c 'unix 'windows) = (system-path-convention-type)
  false-on-non-element? : any/c = #f
```


# 14.15 Deprecation
Like bytes  →  path, except that bstr corresponds to a single relative element in a path. In terms of conversions, restrictions on bstr, and the treatment of false-on-non-element?, bytes  →  path-element is like string  →  path-element.
The bytes  →  path-element procedure is generally the best choice for reconstructing a path based on another path (where the other path is deconstructed with split-path and path-element  →  bytes) when ASCII-level manipulation of path elements is necessary.
Changed in version 8.1.0.6 of package base: Added the false-on-non-element? argument.
> ```
(path-element  →  string path)   →   string?
  path : path-element?```
Like [path->string](#%28def._%28%28quote._~23~25kernel%29._path-~3estring%29%29), except that trailing path separators are removed (as by [split-path](#%28def._%28%28quote._~23~25kernel%29._split-path%29%29)). On Windows, any \\\\?\\REL encoding prefix is also removed; see [Windows Paths](windowspaths.html) for more information.
The path argument must be such that [split-path](#%28def._%28%28quote._~23~25kernel%29._split-path%29%29) applied to path would return 'relative as its first result and a path as its second result, otherwise the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
The [path-element->string](#%28def._%28%28quote._~23~25kernel%29._path-element-~3estring%29%29) procedure is generally the best choice for presenting a pathless file or directory name to a user.
> ```


# 14.15 Deprecation
(path-element  →  bytes path)  →  bytes?
  path : path-element?
```
Like path  →  bytes, except that any encoding prefix is removed, etc., as for path-element  →  string.

For any reasonable locale, consecutive ASCII characters in the printed form of path are mapped to consecutive byte values that match each character’s code-point value, and a leading or trailing ASCII character is mapped to a leading or trailing byte, respectively. The path argument can be a path for any platform.

The path-element  →  bytes procedure is generally the right choice (in combination with split-path) for extracting the content of a path to manipulate it at the ASCII level (then reassembling the result with bytes  →  path-element and build-path).

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>procedure</p>

<p>(path<? a-path b-path ...)  →  boolean?</p></blockquote></td></tr><tr><td>  a-path : path?</td></tr><tr><td>  b-path : path?</td></tr></tbody></table>

Returns #t if the arguments are sorted, where the comparison for each pair of paths is the same as using path  →  bytes and bytes<?.

Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.

> ```
(path-convention-type path) → (or/c 'unix 'windows)
  path : path-for-some-system?```

Accepts a path value (not a string) and returns its convention type.

> ```
(system-path-convention-type)  →  (or/c 'unix 'windows)
```


# 14.15 Deprecation
Returns the path convention type of the current platform: 'unix for Unix and Mac OS, 'windows for Windows.
> ```
(build-path base sub ...) → path-for-some-system?
  base : (or/c path-string? path-for-some-system? 'up 'same)
   sub   :   ( or/c ( and/c ( or/c path-string? path-for-some-system? )
> ( not/c complete-path? ) )
> ( or/c ' up ' same ) )```
Creates a path given a base path and any number of sub-path extensions. If base is an absolute path, the result is an absolute path, otherwise the result is a relative path.
The base and each sub must be either a relative path, the symbol 'up (indicating the relative parent directory), or the symbol 'same (indicating the relative current directory). For Windows paths, if base is a drive specification (with or without a trailing slash) the first sub can be an absolute (driveless) path. For all platforms, the last sub can be a filename.
The base and sub arguments can be paths for any platform. The platform for the resulting path is inferred from the base and sub arguments, where string arguments imply a path for the current platform. If different arguments are for different platforms, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised. If no argument implies a platform (i.e., all are 'up or 'same), the generated path is for the current platform.
Each sub and base can optionally end in a directory separator. If the last sub ends in a separator, it is included in the resulting path.


# 14.15 Deprecation
If base or sub is an illegal path string (because it is empty or contains a nul character), the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
The [build-path](#%28def._%28%28quote._~23~25kernel%29._build-path%29%29) procedure builds a path without checking the validity of the path or accessing the filesystem.
See [Unix and Mac OS Paths](unixpaths.html) and [Windows Paths](windowspaths.html) for more information on the construction of paths.
The following examples assume that the current directory is "/home/joeuser" for Unix examples and "C:\\Joe’s Files" for Windows examples.
> ```racket
> ( define p1 ( build-path ( current-directory ) "src" "racket" ) )
> ; Unix: p1 is "/home/joeuser/src/racket"
> ; Windows: p1 is "C:\\Joe's Files\\src\\racket"
> ( define p2 ( build-path ' up ' up "docs" "Racket" ) )
> ; Unix: p2 is "../../docs/Racket"
> ; Windows: p2 is "..\\..\\docs\\Racket"
> ( build-path p2 p1 )
> ; Unix and Windows: raises exn:fail:contract ; p1 is absolute
> ( build-path p1 p2 )
> ; Unix: is "/home/joeuser/src/racket/../../docs/Racket"
> ; Windows: is "C:\\Joe's Files\\src\\racket\\..\\..\\docs\\Racket"
> ```
> ```
(build-path/convention-type type
    base
    sub ...)    →    path-for-some-system?
  type : (or/c 'unix 'windows)
  base : (or/c path-string? path-for-some-system? 'up 'same)
   sub   :   ( or/c ( and/c ( or/c path-string? path-for-some-system? )
> ( not/c complete-path? ) )
> ( or/c ' up ' same ) )


# 14.15 Deprecation
```
Like build-path, except a path convention type is specified explicitly.

Note that, just as with build-path, any string arguments for either base or sub will be implicitly converted into a path for the current platform before being combined with the others. For this reason, you cannot use this function to build paths from strings for any platform other than the current one; in such attempts, type does not match the inferred convention type for the strings and an exn:fail:contract exception is raised. (To create paths for foreign platforms, see bytes  →  path.)

The usefulness of build-path/convention-type over build-path is limited to cases where the sub-paths contain 'same or 'up elements.

> ```
(absolute-path? path)   →   boolean?
  path : (or/c path? string? path-for-some-system?)```

Returns #t if path is an absolute path, #f otherwise. The path argument can be a path for any platform. If path is not a legal path string (e.g., it contains a nul character), #f is returned. This procedure does not access the filesystem.

> ```
(relative-path? path)  →  boolean?
  path : (or/c path? string? path-for-some-system?)
```
Returns #t if path is a relative path, #f otherwise. The path argument can be a path for any platform. If path is not a legal path string (e.g., it contains a nul character), #f is returned. This procedure does not access the filesystem.
> ```
(complete-path? path)   →   boolean?
  path : (or/c path? string? path-for-some-system?)```


# 14.15 Deprecation
Returns #t if path is a completely determined path (not relative to a directory or drive), #f otherwise. The path argument can be a path for any platform. Note that for Windows paths, an absolute path can omit the drive specification, in which case the path is neither relative nor complete. If path is not a legal path string (e.g., it contains a nul character), #f is returned.
This procedure does not access the filesystem.
> ```
(current-directory)	→
(-> or/c path-string? path-for-some-system?)
```
Returns path as a complete path. If path is already a complete path, it is returned as the result. Otherwise, path is resolved with respect to the complete path base. If base is not a complete path, the exn:fail:contract exception is raised.

The path and base arguments can be paths for any platform; if they are for different platforms, the exn:fail:contract exception is raised.

This procedure does not access the filesystem.

> ```
(path  →  directory-path path)   →   path-for-some-system?
  path : (or/c path-string? path-for-some-system?)```

Returns path if path syntactically refers to a directory and ends in a separator, otherwise it returns an extended version of path that specifies a directory and ends with a separator. For example, on Unix and Mac OS, the path "x/y/" syntactically refers to a directory and ends in a separator, but "x/y" would be extended to "x/y/", and "x/.." would be extended to "x/../". The path argument can be a path for any platform, and the result will be for the same platform.

This procedure does not access the filesystem.

> ```
(resolve-path path)  →  path?
  path : path-string?
```


# 14.15 Deprecation
Cleanses path and returns a path that references the same file or directory as path. If path is a soft link to another path, then the referenced path is returned (this may be a relative path with respect to the directory owning path), otherwise path is returned (after cleansing).
On Windows, the path for a link should be simplified syntactically, so that an up-directory indicator removes a preceding path element independent of whether the preceding element itself refers to a link. For relative-paths links, the path should be parsed specially; see Windows Paths for more information.
Changed in version 6.0.1.12 of package base: Added support for links on Windows.
> ```
(cleanse-path path)   →   path-for-some-system?
  path : (or/c path-string? path-for-some-system?)```
[Cleanse](pathutils.html#%28tech._cleanse%29)s path (as described at the beginning of this chapter) without consulting the filesystem.
Example:
> ```racket
> > ( let ( [ p ( string->some-system-path "tiny//dancer" ' unix ) ] ) ( cleanse-path p ) )
> #<path:tiny/dancer>
> ```
> ```
(expand-user-path path)  →  path?
  path : path-string?


# 14.15 Deprecation
```
Cleanses path. In addition, on Unix and Mac OS, a leading \~ is treated as user’s home directory and expanded; the username follows the \~ (before a / or the end of the path), where \~ by itself indicates the home directory of the current user.

> ```
(simplify-path path [use-filesystem?) → path-for-some-system?
  path : (or/c path-string? path-for-some-system?)
  use-filesystem? : boolean? = #t```

Eliminates redundant path separators (except for a single trailing separator), up-directory .., and same-directory . indicators in path, and changes / separators to \\ separators in Windows paths, such that the result accesses the same file or directory (if it exists) as path.

In general, the pathname is normalized as much as possible—without consulting the filesystem if use-filesystem? is #f, and (on Windows) without changing the case of letters within the path. If path syntactically refers to a directory, the result ends with a directory separator.

When path is simplified other than just converting slashes to backslashes and use-filesystem? is true (the default), a complete path is returned. If path is relative, it is resolved with respect to the current directory. On Unix and Mac OS, up-directory indicators are removed taking into account soft links (so that the resulting path refers to the same directory as before); on Windows, up-directory indicators are removed by deleting a preceding [path element](More_Path_Utilities.html#%28tech._path._element%29).

When use-filesystem? is #f, up-directory indicators are removed by deleting a preceding [path element](More_Path_Utilities.html#%28tech._path._element%29), and the result can be a relative path with up-directory indicators remaining at the beginning of the path; up-directory indicators are dropped when they refer to the parent of a root directory. Similarly, the result can be the same as ([build-path](#%28def._%28%28quote._~23~25kernel%29._build-path%29%29) 'same) (but with a trailing separator) if eliminating up-directory indicators leaves only same-directory indicators.

The path argument can be a path for any platform when use-filesystem? is #f, and the resulting path is for the same platform.

The filesystem might be accessed when use-filesystem? is true, but the source or simplified path might be a non-existent path. If path cannot be simplified due to a cycle of links, the [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception is raised (but a successfully simplified path may still involve a cycle of links if the cycle did not inhibit the simplification).

See [Unix and Mac OS Paths](unixpaths.html) and [Windows Paths](windowspaths.html) for more information on simplifying paths.

Example:

> ```racket
> > ( let ( [ p ( string->some-system-path "tiny//in/my/head/../../../dancer" ' unix ) ] ) ( simplify-path p #f ) )
> #<path:tiny/dancer>
> ```

> ```
(normal-case-path path)  →  path-for-some-system?
  path : (or/c path-string? path-for-some-system?)
```