# 12.2 Syntax Object Content
```
For backward compatibility only; returns a procedure that returns its first argument.

#### 12.4.2 provide Transformers

|  |  |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require racket/provide-transform) |  package: base |

The bindings documented in this section are provided by the racket/provide-transform library, not racket/base or racket.

A transformer binding whose value is a structure with the prop:provide-transformer property implements a derived provide-spec for provide as a provide transformer. A provide transformer is applied as part of the last phase of a module’s expansion, after all other declarations and expressions within the module are expanded.

A transformer binding whose value is a structure with the prop:provide-pre-transformer property implements a derived provide-spec for provide as a provide pre-transformer. A provide pre-transformer is applied as part of the first phase of a module’s expansion. Since it is used in the first phase, a provide pre-transformer can use functions such as syntax-local-lift-expression to introduce expressions and definitions in the enclosing module.

An identifier can have a transformer binding to a value that acts both as a provide transformer and provide pre-transformer. The result of a provide pre-transformer is not automatically re-expanded, so a provide pre-transformer can usefully expand to itself in that case.

A transformer is called with the syntax object representing its use as a provide-spec within a provide form and a list of symbols representing the export modes specified by enclosing provide-specs. The result of a provide transformer must be a list of exports, while the result of a provide pre-transformer is a syntax object to be used as a provide-spec in the last phase of module expansion.

If a derived form contains a sub-form that is a provide-spec, then it can call expand-export or pre-expand-export to transform the sub-provide-spec sub-form.

See also define-provide-syntax, which supports macro-style provide transformers.

> ```
(expand-export provide-spec modes) → (listof export?)
  provide-spec : syntax?
  modes : (listof phase+space?)```

Expands the given provide-spec to a list of exports. The modes list controls the expansion of sub-provide-specs; for example, an identifier refers to a binding in the [phase level](syntax-model.html#%28tech._phase._level%29) of the enclosing [provide](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._provide%29%29) form, unless the modes list specifies otherwise. Normally, modes is either empty or contains a single element.

Changed in version 8.2.0.3 of package base: Generalized modes to phase–space combinations.

> ```
(pre-expand-export provide-spec modes)  →  syntax?
  provide-spec : syntax?
  modes : (listof phase+space?)
```


# 12.2 Syntax Object Content
Expands the given provide-spec at the level of provide pre-transformers. The modes argument is the same as for expand-export.
Changed in version 8.2.0.3 of package base: Generalized modes to phase–space combinations.
> ```
(make-provide-transformer proc)   →   provide-transformer?
   proc   :   ( syntax? ( listof phase+space? )
> .  →  . ( listof export? ) )
(make-provide-transformer proc pre-proc)
   →   (and/c provide-transformer? provide-pre-transformer?)
   proc   :   ( syntax? ( listof phase+space? )
> .  →  . ( listof export? ) )
   pre-proc   :   ( syntax? ( listof phase+space? )
> .  →  . syntax? )```
Creates a [provide transformer](#%28tech._provide._transformer%29) (i.e., a structure with the [prop:provide-transformer](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._prop~3aprovide-transformer%29%29) property) using the given procedure as the transformer. If a pre-proc is provided, then the result is also a [provide pre-transformer](#%28tech._provide._pre._transformer%29). Often used in combination with [expand-export](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._expand-export%29%29) and/or [pre-expand-export](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._pre-expand-export%29%29).
> ```
(make-provide-pre-transformer pre-proc)
  →  provide-pre-transformer?
   pre-proc   :   ( syntax? ( listof phase+space? )
> .  →  . syntax? )


# 12.2 Syntax Object Content
```
Like make-provide-transformer, but for a value that is a provide pre-transformer, only. Often used in combination with pre-expand-export.

Examples:

> ```racket
> > ( module m racket ( require ( for-syntax racket/provide-transform syntax/parse syntax/stx ) ) ( define-syntax wrapped-out ( make-provide-pre-transformer ( lambda ( stx modes ) ( syntax-parse stx [ ( _ f ... ) #:with ( wrapped-f ... ) ( stx-map syntax-local-lift-expression #' ( ( lambda args ( printf "applying ~a, args: ~a\n" ' f args ) ( apply f args ) ) ... ) ) ( pre-expand-export #' ( rename-out [ wrapped-f f ] ... ) modes ) ] ) ) ) ) ( provide ( wrapped-out + - ) ) )
> > ( require ' m )
> > ( - 1 ( + 2 3 ) )
> applying +, args: (2 3) applying -, args: (1 5)
> -4
> ```

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

<p>value</p>

<p>prop:provide-transformer : struct-type-property?</p></blockquote></td></tr></tbody></table>

A property to identify provide transformers. The property value must be a procedure that takes the structure and returns a transformer procedure; the returned transformer procedure takes a syntax object and mode list and returns an export list.

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

<p>value</p>

<p>prop:provide-pre-transformer : struct-type-property?</p></blockquote></td></tr></tbody></table>

A property to identify provide pre-transformers. The property value must be a procedure that takes the structure and returns a transformer procedure; the returned transformer procedure takes a syntax object and mode list and returns a syntax object.

> ```
(provide-transformer? v) → boolean?
  v : any/c```

Returns #t if v has the [prop:provide-transformer](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._prop~3aprovide-transformer%29%29) property, #f otherwise.

> ```
(provide-pre-transformer? v)  →  boolean?
  v : any/c
```


# 12.2 Syntax Object Content
(parameter)	→```
Composes [syntax-e](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-e%29%29) with [export-out-id](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._export-out-id%29%29).
This function is intended for backward compatibility. Use [export-out-id](#%28def._%28%28lib._racket%2Fprovide-transform..rkt%29._export-out-id%29%29) directly, instead.
Added in version 8.9.0.5 of package base.
> ```
(syntax-local-provide-certifier)
   →    ( ( syntax? ) ( or/c #f ( syntax? .  →  . syntax? ) )
> .  →  * . syntax? )
```
For backward compatibility only; returns a procedure that returns its first argument.

#### 12.4.3 Keyword-Argument Conversion Introspection

|  |  |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require racket/keyword-transform) |  package: base |

The bindings documented in this section are provided by the racket/keyword-transform library, not racket/base or racket.

> ```
(syntax-procedure-alias-property stx)
   →    ( or/c #f
> ( letrec ( [ val? ( recursive-contract
> ( or/c ( cons/c identifier? identifier? )
> ( cons/c val? val? ) ) ) ] )
> val? ) )

  stx : syntax?

(syntax-procedure-converted-arguments-property stx)
   →    ( or/c #f
> ( letrec ( [ val? ( recursive-contract
> ( or/c ( cons/c identifier? identifier? )
> ( cons/c val? val? ) ) ) ] )
> val? ) )

  stx : syntax?```

Reports the value of a syntax property that can be attached to an identifier by the expansion of a keyword-application form. See [lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) for more information about the property.

The property value is normally a pair consisting of the original identifier and an identifier that appears in the expansion. Property-value merging via [syntax-track-origin](stxprops.html#%28def._%28%28quote._~23~25kernel%29._syntax-track-origin%29%29) can make the value a pair of such values, and so on.

#### 12.4.4 Portal Syntax Bindings

An identifier bound to portal syntax value created by [make-portal-syntax](#%28def._%28%28quote._~23~25kernel%29._make-portal-syntax%29%29) does not act as a transformer, but it encapsulates a syntax object that can be accessed and inspected even without instantiating the enclosing module. Portal syntax is also bound using the portal form of [#%require](require.html#%28form._%28%28quote._~23~25kernel%29._~23~25require%29%29).

> ```
(portal-syntax? v)  →  boolean?
  v : any/c
```


# 12.2 Syntax Object Content
Returns #t if v is a value created by make-portal-syntax, #f otherwise.
Added in version 8.3.0.8 of package base.
> ```
(make-portal-syntax stx)   →   portal-syntax?
  stx : syntax?```
Creates [portal syntax](#%28tech._portal._syntax%29) with the content stx.
When [define-syntax](define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define-syntax%29%29) or [define-syntaxes](define.html#%28form._%28%28quote._~23~25kernel%29._define-syntaxes%29%29) binds an identifier to portal syntax immediately in a module body, then in addition to being accessible via [syntax-local-value](#%28def._%28%28quote._~23~25kernel%29._syntax-local-value%29%29) while expanding, the portal syntax content is accessible via [identifier-binding-portal-syntax](stxcmp.html#%28def._%28%28quote._~23~25kernel%29._identifier-binding-portal-syntax%29%29).
Added in version 8.3.0.8 of package base.
> ```
(portal-syntax-content portal)  →  syntax?
  portal : portal-syntax?


# 12.2 Syntax Object Content
```
(parameter)	→```

This procedure is intended for use in a [transformer environment](syntax-model.html#%28tech._transformer._environment%29), where id-stx is an identifier bound in the normal environment to a [syntax parameter](#%28tech._syntax._parameter%29). The result is the current value of the [syntax parameter](#%28tech._syntax._parameter%29), as adjusted by [syntax-parameterize](#%28form._%28%28lib._racket%2Fstxparam..rkt%29._syntax-parameterize%29%29) form.

This binding is provided [for-syntax](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for-syntax%29%29) by [racket/stxparam](), since it is normally used in a transformer. It is provided normally by [racket/stxparam-exptime](#%28mod-path._racket%2Fstxparam-exptime%29).

> ```
(parameter)	→
```
(parameter)	→
(-> if preserved? (and/c symbol? symbol-interned?) any/c)```
The three- or four-argument form extends stx by associating an arbitrary property value v with the key key; the result is a new syntax object with the association (while stx itself is unchanged). The property is added as [preserved](#%28tech._stx._prop._preserved%29) if preserved? is true, in which case key must be an [interned](reader.html#%28tech._interned%29) symbol, and v should be a value as described below that can be saved in marshaled bytecode.


# 12.2 Syntax Object Content
The two-argument form returns an arbitrary property value associated to stx with the key key, or #f if no value is associated to stx for key. If stx is [tainted](stxcerts.html#%28tech._tainted%29), then syntax objects with the result value are tainted.
To support marshaling to bytecode, a value for a preserved syntax property must be a non-cyclic value that is either
-   a [pair](pairs.html#%28tech._pair%29) containing allowed preserved-property values;
-   a [vector](vectors.html#%28tech._vector%29) (unmarshaled as immutable) containing allowed preserved-property values;
-   a [box](boxes.html#%28tech._box%29) (unmarshaled as immutable) containing allowed preserved-property values;
-   an immutable [prefab](structures.html#%28tech._prefab%29) structure containing allowed preserved-property values;
-   an immutable [hash table](hashtables.html#%28tech._hash._table%29) whose keys and values are allowed preserved-property values;
-   a [syntax object](syntax-model.html#%28tech._syntax._object%29); or
-   an empty list, [symbol](symbols.html#%28tech._symbol%29), [number](numbers.html#%28tech._number%29), [character](characters.html#%28tech._character%29), [string](strings.html#%28tech._string%29), [byte string](bytestrings.html#%28tech._byte._string%29), or [regexp value](regexp.html#%28tech._regexp._value%29).
Any other value for a preserved property triggers an exception at an attempt to marshal the owning syntax object to bytecode form.
Changed in version 6.4.0.14 of package base: Added the preserved? argument.
> ```


# 12.2 Syntax Object Content
(syntax-property-remove stx key)  →  syntax?
  stx : syntax?
  key : any/c
```
(parameter)	→
(-> and/c symbol? symbol-interned?)```

Returns #t if stx has a [preserved](#%28tech._stx._prop._preserved%29) property value for key, #f otherwise.

Added in version 6.4.0.14 of package base.

> ```
(syntax-property-symbol-keys stx)  →  list?
  stx : syntax?
```
Returns a list of all symbols that as keys have associated properties in stx. Uninterned symbols (see Symbols) are not included in the result list.
> ```
(syntax-track-origin   new-stx
    orig-stx
    id-stx)    →    any
  new-stx : syntax?
  orig-stx : syntax?
  id-stx : identifier?```
Adds properties to new-stx in the same way that macro expansion adds properties to a transformer result. In particular, it merges the properties of orig-stx into new-stx, first adding id-stx as an 'origin property and removing the property recognized by [syntax-original?](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-original~3f%29%29), and it returns the property-extended syntax object. Use the [syntax-track-origin](#%28def._%28%28quote._~23~25kernel%29._syntax-track-origin%29%29) procedure in a macro transformer that discards syntax (corresponding to orig-stx with a keyword id-stx) leaving some other syntax in its place (corresponding to new-stx).
For example, the expression
> ([or](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._or%29%29) x y)
expands to


# 12.2 Syntax Object Content
> ([let](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29) (\[or-part x\]) ([if](if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29) or-part or-part ([or](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._or%29%29) y)))
which, in turn, expands to
> ([let-values](let.html#%28form._%28%28quote._~23~25kernel%29._let-values%29%29) (\[(or-part) x\]) ([if](if.html#%28form._%28%28quote._~23~25kernel%29._if%29%29) or-part or-part y))
The syntax object for the final expression will have an 'origin property whose value is ([list](pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29) ([quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) [let](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29)) ([quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) [or](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._or%29%29))).
Changed in version 7.0 of package base: Included the [syntax-original?](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-original~3f%29%29) property among the ones transferred to new-stx.
Changed in version 8.2.0.7: Corrected back to removing the [syntax-original?](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-original~3f%29%29) property from the set transferred to new-stx.
------------------------------------------------------------------------


# 12.8 Syntax Taints


### 12.8 Syntax Taints
> > > <img src="finger.png" width="24" height="24" alt="+" />[Tainted Syntax](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=stx-certs.html&version=8.18.0.13) in [The Racket Guide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.18.0.13) introduces syntax taints.
A tainted identifier is rejected by the macro expander for use as either a binding or expression. If a syntax object stx is [tainted](#%28tech._tainted%29), then any syntax object in the result of ([syntax-e](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-e%29%29) stx) is [tainted](#%28tech._tainted%29), and [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) with stx as its first argument produces a [tainted](#%28tech._tainted%29) syntax object. Any syntax object in the result of ([syntax-property](stxprops.html#%28def._%28%28quote._~23~25kernel%29._syntax-property%29%29) stx key) is also tainted if it is in a position within the value that would be reached by [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29)’s conversion. Taints cannot be removed.


# 12.8 Syntax Taints
A syntax object is tainted when it is included in an exception by the macro expander or when it is produced by a function like [expand](Expanding_Top-Level_Forms.html#%28def._%28%28quote._~23~25kernel%29._expand%29%29) using a [code inspector](modprotect.html#%28tech._code._inspector%29) that is not the original code inspector. The function [syntax-taint](#%28def._%28%28quote._~23~25kernel%29._syntax-taint%29%29) also returns a tainted syntax object.
Previous versions of Racket included a notion of arming and disarming syntax to trigger taints or avoid taints. That indirection is no longer supported, and the operations [syntax-arm](#%28def._%28%28quote._~23~25kernel%29._syntax-arm%29%29), [syntax-disarm](#%28def._%28%28quote._~23~25kernel%29._syntax-disarm%29%29), [syntax-rearm](#%28def._%28%28quote._~23~25kernel%29._syntax-rearm%29%29), and [syntax-protect](#%28def._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-protect%29%29) now have no effect on their arguments. Along similar lines, the syntax properties (see [Syntax Object Properties](stxprops.html)) 'taint-mode and 'certify-mode were formerly used to control syntax arming and are no longer specifically recognized by the macro expander.
> ```
(syntax-tainted? stx)  →  boolean?
  stx : syntax?


# 12.8 Syntax Taints
```
Returns #t if stx is tainted, #f otherwise.

> ```
(syntax-arm stx [inspector use-mode?) → syntax?
  stx : syntax?
  inspector : (or/c inspector? #f) = #f
  use-mode? : any/c = #f```

Returns stx.

Changed in version 8.2.0.4 of package base: Changed to just return stx instead of returning “armed” syntax.

> ```
(syntax-protect stx)  →  syntax?
  stx : syntax?
```
Returns stx.
Changed in version 8.2.0.4 of package base: Changed to just return stx instead of returning “armed” syntax.
> ```
(syntax-disarm stx inspector)  →  syntax?
  stx : syntax?
  inspector : (or/c inspector? #f)
```

Returns stx.

Changed in version 8.2.0.4 of package base: Changed to just return stx instead of potentially “disarming” syntax.

> ```
(syntax-rearm stx from-stx [use-mode?) → syntax?
  stx : syntax?
  from-stx : syntax?
  use-mode? : any/c = #f
```
Returns stx.
Changed in version 8.2.0.4 of package base: Changed to just return stx instead of potentially “arming” syntax.
> ```
(syntax-taint stx)  →  syntax?
  stx : syntax?
```

Returns [tainted](#%28tech._tainted%29) version of stx, which is stx if it is already tainted.

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

# 12.9 Expanding Top-Level Forms

### 12.9 Expanding Top-Level Forms

> ```
(current-code-inspector)	→
(-> current-code-inspector)
```
(current-code-inspector)	→
(-> i.e., the value of (current-code-inspector) when Racket starts)```


# 12.8 Syntax Taints
Like ([expand](#%28def._%28%28quote._~23~25kernel%29._expand%29%29) stx insp), except that the argument must be a [syntax object](syntax-model.html#%28tech._syntax._object%29), and its lexical context is not enriched before expansion.
Changed in version 8.2.0.4 of package base: Added the insp argument and tainting.
> ```
(current-code-inspector)	→
(-> current-code-inspector)
```
(current-code-inspector)	→
(-> current-code-inspector)```

Like ([expand-once](#%28def._%28%28quote._~23~25kernel%29._expand-once%29%29) stx), except that the argument must be a [syntax object](syntax-model.html#%28tech._syntax._object%29), and its lexical context is not enriched before expansion.

Changed in version 8.2.0.4 of package base: Added the insp argument and tainting.

> ```
(current-code-inspector)	→
(-> current-code-inspector)
```
(current-code-inspector)	→
(-> current-code-inspector)```
Like ([expand-to-top-form](#%28def._%28%28quote._~23~25kernel%29._expand-to-top-form%29%29) stx), except that the argument must be a [syntax object](syntax-model.html#%28tech._syntax._object%29), and its lexical context is not enriched before expansion.
Changed in version 8.2.0.4 of package base: Added the insp argument and tainting.


#### 12.9.1 Information on Expanded Modules
Information for an expanded [module](module.html#%28form._%28%28quote._~23~25kernel%29._module%29%29) declaration is stored in a set of [syntax properties](stxprops.html#%28tech._syntax._property%29) (see [Syntax Object Properties](stxprops.html)) attached to the syntax object:
-   'module-body-context — a syntax object whose [lexical information](syntax-model.html#%28tech._lexical._information%29) corresponds to the inside of the module, so it includes the expansion’s [outside-edge scope](syntax-model.html#%28tech._outside._edge._scope%29) and its [inside-edge scope](syntax-model.html#%28tech._inside._edge._scope%29); that is, the syntax object simulates an identifier that is present in the original module body and inaccessible to manipulation by any macro, so that its lexical information includes bindings for the module’s imports and definitions.
    Added in version 6.4.0.1 of package base.
-   'module-body-inside-context — a syntax object whose [lexical information](syntax-model.html#%28tech._lexical._information%29) corresponds to an identifier that starts with no lexical context and is moved into the macro, so that it includes only the expansions’s [inside-edge scope](syntax-model.html#%28tech._inside._edge._scope%29).
    Added in version 6.4.0.1 of package base.


# 12.8 Syntax Taints
-   'module-body-context-simple? — a boolean, where #t indicates that the bindings of the module’s body (as recorded in the [lexical information](syntax-model.html#%28tech._lexical._information%29) of the value of the 'module-body-inside-context property) can be directly reconstructed from modules directly imported into the module, including imported for-syntax, for-meta, and for-template.
    Added in version 6.4.0.1 of package base.
Changed in version 7.0 of package base: Removed 'module-variable-provides, 'module-syntax-provides, 'module-indirect-provides, and 'module-indirect-for-meta-provides properties.
------------------------------------------------------------------------


# 12.10 Serializing Syntax


### 12.10 Serializing Syntax
> ```
(current-namespace)	→
(-> listof symbol?)
```
Converts stx to a serialized form that is suitable for use with s-exp  →  fasl or serialize. Although stx could be serialized with (compile \`(quote-syntax ,stx)) and then writing the compiled form, syntax-serialize provides more control over serialization:

-  The preserve-property-keys lists syntax-property keys to whose values should be preserved in serialization, even if the property value was not added as preserved with syntax-property (so it would be discarded in compiled form). The values associated with the properties to preserve must be serializable in the sense required by syntax-property for a preserved property.

-  The provides-namespace argument constrains how much the serialized syntax object can rely on bulk bindings, which are shared binding tables provided by exporting modules. If provides-namespace is #f, then complete binding information is recorded in the syntax object’s serialized form, and no bulk bindings will be needed from the namespace at deserialization. Otherwise, bulk bindings will be used only for modules declared in provides-namespace (i.e., the deserialize-time namespace will have the same module declarations as provides-namespace); note that supplying a namespace with no module bindings is equivalent to supplying #f.

-  The base-module-path-index argument specifies a module path index to which binding information in stx is relative. For example, if a syntax object originates from quote-syntax in the body of a module, then base-module-path-index could usefully be the enclosing module’s module path index as produced by (variable-reference  →  module-path-index (#%variable-reference)) within the module. On deserialization, a different module path index can be supplied to substitute in place of base-module-path-index, which shifts any binding that is relative to the serialize-time module’s identity to be relative to the module identity supplied at deserialize time. If base-module-path-index is #f, then no shifting is supported at deserialize time, and any base-module-path-index supplied at that time is ignored.

A serialized syntax object is otherwise similar to compiled code: it is version-specific, and deserialization will require a sufficiently powerful code inspector.

Added in version 8.0.0.13 of package base.

> ```
(syntax-deserialize
    v
   [ #:base-module-path-index base-module-path-index)

   →   syntax?
  v : any/c
  base-module-path-index : (or/c module-path-index? #f) = #f```

Converts the result of [syntax-serialize](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._syntax-serialize%29%29) back to a syntax object. See [syntax-serialize](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._syntax-serialize%29%29) for more information.

Added in version 8.0.0.13 of package base.

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

# 12.11 File Inclusion

### 12.11 File Inclusion

|                                                                                |                                                                                |
|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/include]()) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |

The bindings documented in this section are provided by the [racket/include]() and [racket](index.html) libraries, but not [racket/base](index.html).

>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29) path-spec)

path-spec	 	=	 	string

 	 	|	 	([file](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._file%29%29) string)

 	 	|	 	([lib](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lib%29%29) string ...+)

Inlines the syntax in the file designated by path-spec in place of the [include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29) expression.

A path-spec resembles a subset of the mod-path forms for [require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29), but it specifies a file whose content need not be a module. That is, string refers to a file using a platform-independent relative path, ([file](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._file%29%29) string) refers to a file using platform-specific notation, and ([lib](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lib%29%29) string [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) refers to a file within a collection.

If path-spec specifies a relative path, the path is resolved relative to the source for the [include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29) expression, if that source is a complete path string. If the source is not a complete path string, then path-spec is resolved relative to ([current-load-relative-directory](eval.html#%28def._%28%28quote._~23~25kernel%29._current-load-relative-directory%29%29)) if it is not #f, or relative to ([current-directory](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29)) otherwise.

The included syntax is given the lexical context of the [include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29) expression, while the included syntax’s source location refers to its actual source.

>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([include-at/relative-to](#%28form._%28%28lib._racket%2Finclude..rkt%29._include-at%2Frelative-to%29%29) context source path-spec)

Like [include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29), except that the lexical context of context is used for the included syntax, and a relative path-spec is resolved with respect to the source of source. The context and source elements are otherwise discarded by expansion.

>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([include/reader](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%2Freader%29%29) path-spec reader-expr)

Like [include](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%29%29), except that the procedure produced by the expression reader-expr is used to read the included file, instead of [read-syntax](Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29).

The reader-expr is evaluated at expansion time in the [transformer environment](syntax-model.html#%28tech._transformer._environment%29). Since it serves as a replacement for [read-syntax](Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29), the expression’s value should be a procedure that consumes two inputs—a string representing the source and an input port—and produces a syntax object or [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29). The procedure will be called repeatedly until it produces [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29).

The syntax objects returned by the procedure should have source location information, but usually no lexical context; any lexical context in the syntax objects will be ignored.

>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([include-at/relative-to/reader](#%28form._%28%28lib._racket%2Finclude..rkt%29._include-at%2Frelative-to%2Freader%29%29) context source path-spec reader-expr)

Combines [include-at/relative-to](#%28form._%28%28lib._racket%2Finclude..rkt%29._include-at%2Frelative-to%29%29) and [include/reader](#%28form._%28%28lib._racket%2Finclude..rkt%29._include%2Freader%29%29).

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

# 12.12 Syntax Utilities

### 12.12 Syntax Utilities

|                                                                                |                                                                                |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/syntax]()) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |

The bindings documented in this section are provided by the [racket/syntax]() library, not [racket/base](index.html) or [racket](index.html).

#### 12.12.1 Creating formatted identifiers

> ```
(parameter)	→
(-> or/c syntax? #f)
```


# 12.10 Serializing Syntax
(parameter)	→
(-> e.g., identifiers will be automatically converted to symbols)```
Like [format](Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29), but produces a symbol. The format string must use only \~a placeholders. Syntax objects in the argument list are automatically unwrapped (e.g., identifiers will be automatically converted to symbols).
Example:
> ```racket
> > ( format-symbol "make-~a" ' triple )
> 'make-triple
> ```
Changed in version 8.7.0.7 of package base: Allowed v to be a syntax object wrapping a string, a keyword, a character, or a number.


#### 12.12.2 Pattern variables
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([define/with-syntax](#%28form._%28%28lib._racket%2Fsyntax..rkt%29._define%2Fwith-syntax%29%29) pattern stx-expr)

  	stx-expr	 	:	 	[syntax?](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax~3f%29%29)

Definition form of [with-syntax](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29). That is, it matches the syntax object result of stx-expr against pattern and creates pattern variable definitions for the pattern variables of pattern.
Examples:
> ```racket
> > ( define/with-syntax ( px ... ) #' ( a b c ) )
> > ( define/with-syntax ( tmp ... ) ( generate-temporaries #' ( px ... ) ) )
> > #' ( [ tmp px ] ... )
> #<syntax:eval:12:0 ((a9 a) (b10 b) (c11 c))>
> > ( define/with-syntax name #' Alice )
> > #' ( hello name )
> #<syntax:eval:14:0 (hello Alice)>
> ```


#### 12.12.3 Error reporting
> ```
(current-syntax-context)	→
(-> or/c syntax? #f)
(current-syntax-context stx) → void?
    stx	:
(-> or/c syntax? #f)
```
The current contextual syntax object, defaulting to #f. It determines the special form name that prefixes syntax errors created by wrong-syntax.

> ```
(wrong-syntax stx format-string v ...) → any
  stx : syntax?
  format-string : string?
  v : any/c```

Raises a syntax error using the result of ([current-syntax-context](#%28def._%28%28lib._racket%2Fsyntax..rkt%29._current-syntax-context%29%29)) as the “major” syntax object and the provided stx as the specific syntax object. (The latter, stx, is usually the one highlighted by DrRacket.) The error message is constructed using the format string and arguments, and it is prefixed with the special form name as described under [current-syntax-context](#%28def._%28%28lib._racket%2Fsyntax..rkt%29._current-syntax-context%29%29).

Examples:

> ```racket
> > ( wrong-syntax #' here "expected ~s" ' there )
> eval:15:0: ?: expected there
> at: here
> > ( parameterize ( [ current-syntax-context #' ( look over here ) ] ) ( wrong-syntax #' here "expected ~s" ' there ) )
> eval:16:0: look: expected there
> at: here
> in: (look over here)
> ```

A macro using [wrong-syntax](#%28def._%28%28lib._racket%2Fsyntax..rkt%29._wrong-syntax%29%29) might set the syntax context at the very beginning of its transformation as follows:

> ```racket
> ( define-syntax ( my-macro stx )
> ( parameterize ( [ current-syntax-context stx ] )
> ( syntax-case stx ( )
> __ ) ) )
> ```

Then any calls to [wrong-syntax](#%28def._%28%28lib._racket%2Fsyntax..rkt%29._wrong-syntax%29%29) during the macro’s transformation will refer to my-macro (more precisely, the name that referred to my-macro where the macro was used, which may be different due to renaming, prefixing, etc).

#### 12.12.4 Recording disappeared uses

> ```
(current-recorded-disappeared-uses)	→
(-> or/c (listof identifier?) #f)
(current-recorded-disappeared-uses ids) → void?
    ids	:
(-> or/c (listof identifier?) #f)
```


# 12.10 Serializing Syntax
Parameter for tracking disappeared uses. Tracking is “enabled” when the parameter has a non-false value. This is done automatically by forms like with-disappeared-uses.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

(with-disappeared-uses body-expr ... stx-expr)

  	stx-expr	 	:	 	syntax?

Evaluates the body-exprs and stx-expr, catching identifiers looked up using syntax-local-value/record. Adds the caught identifiers to the 'disappeared-use syntax property of the syntax object produced by stx-expr.
Changed in version 6.5.0.7 of package base: Added the option to include body-exprs.
> ```
(syntax-local-value/record id predicate) → any/c
  id : identifier?
  predicate : (  →   any/c boolean?)```
Looks up id in the syntactic environment (as [syntax-local-value](stxtrans.html#%28def._%28%28quote._~23~25kernel%29._syntax-local-value%29%29)). If the lookup succeeds and returns a value satisfying the predicate, the value is returned and id is recorded as a disappeared use by calling [record-disappeared-uses](#%28def._%28%28lib._racket%2Fsyntax..rkt%29._record-disappeared-uses%29%29). If the lookup fails or if the value does not satisfy the predicate, #f is returned and the identifier is not recorded as a disappeared use.
> ```


# 12.10 Serializing Syntax
(parameter)	→
(-> or/c identifier? (listof identifier?))
```
(current-recorded-disappeared-uses)	→```

Generates one fresh identifier. Singular form of [generate-temporaries](stxops.html#%28def._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._generate-temporaries%29%29). If name-base is supplied, it is used as the basis for the identifier’s name.

> ```
(internal-definition-context-apply   intdef-ctx
    stx)    →    syntax?

  intdef-ctx : internal-definition-context?
  stx : syntax?
```
Equivalent to (internal-definition-context-introduce intdef-ctx stx 'add). The internal-definition-context-apply function is provided for backwards compatibility; the internal-definition-context-add-scopes function is preferred.
> ```
(syntax-local-eval stx [intdef-ctx) → any
  stx : any/c
   intdef-ctx   :   ( or/c internal-definition-context?
> #f
> ( listof internal-definition-context? ) )
      =   '()```
Evaluates stx as an expression in the current [transformer environment](syntax-model.html#%28tech._transformer._environment%29) (that is, at [phase level](syntax-model.html#%28tech._phase._level%29) 1). If intdef-ctx is not #f, the value provided for intdef-ctx is used to enrich stx’s [lexical information](syntax-model.html#%28tech._lexical._information%29) and extend the [local binding context](syntax-model.html#%28tech._local._binding._context%29) in the same way as the fourth argument to [local-expand](stxtrans.html#%28def._%28%28quote._~23~25kernel%29._local-expand%29%29).
Examples:


# 12.10 Serializing Syntax
> ```racket
> > ( define-syntax ( show-me stx ) ( syntax-case stx ( ) [ ( show-me expr ) ( begin ( printf "at compile time produces ~s\n" ( syntax-local-eval #' expr ) ) #' ( printf "at run time produces ~s\n" expr ) ) ] ) )
> > ( show-me ( + 2 5 ) )
> at compile time produces 7 at run time produces 7
> > ( define-for-syntax fruit ' apple )
> > ( define fruit ' pear )
> > ( show-me fruit )
> at compile time produces apple at run time produces pear
> ```
Changed in version 6.90.0.27 of package base: Changed intdef-ctx to accept a list of internal-definition contexts in addition to a single internal-definition context or #f.
> ```
syntax
(with-syntax* ([pattern stx-expr] ...)
> body ...+ )
   stx-expr   :   syntax?


# 12.10 Serializing Syntax
```
Similar to with-syntax, but the pattern variables of each pattern are bound in the stx-exprs of subsequent clauses as well as the bodys, and the patterns need not bind distinct pattern variables; later bindings shadow earlier bindings.

Example:

> ```racket
> > ( with-syntax* ( [ ( x y ) ( list #' val1 #' val2 ) ] [ nest #' ( ( x ) ( y ) ) ] ) #' nest )
> #<syntax:eval:22:0 ((val1) (val2))>
> ```

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

# 12.13 Phase and Space Utilities

### 12.13 Phase and Space Utilities

|  |  |
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  (require [racket/phase+space]()) |  package: base |

The bindings documented in this section are provided by the [racket/phase+space]() library, not racket/base or racket.

The [racket/phase+space]() library provides functions for manipulating combined representations of phase levels and binding spaces, particularly as used for require transformers and provide transformers.

When identifier-binding (and related functions, like identifier-transformer-binding), syntax-local-module-exports, syntax-local-module-required-identifiers, module-compiled-exports, or module  →  exports produces a phase–space combination (or phase–space shift combination), then two such values that are equal? will be eqv?.

Added in version 8.2.0.3 of package base.

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

Returns #t if v is a valid representation of a [phase level](syntax-model.html#%28tech._phase._level%29), #f otherwise. A valid representation is either an exact integer representing a numbered phase level or #f representing the [label phase level](syntax-model.html#%28tech._label._phase._level%29).

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


# 12.10 Serializing Syntax
Returns #t if v is a valid representation of a binding space, #f otherwise. A valid representation is either an interned symbol representing the space whose scope is accessed via make-interned-syntax-introducer, or #f representing the default binding space.
> ```
(phase+space? v)   →   boolean?
  v : any/c```
Returns #t if v is a valid representation of a [phase level](syntax-model.html#%28tech._phase._level%29) and [binding space](syntax-model.html#%28tech._binding._space%29) combination, #f otherwise. The possible representations are as follows:
-   a phase (in the sense of [phase?](#%28def._%28%28lib._racket%2Fphase%2Bspace..rkt%29._phase~3f%29%29)) by itself, which represents that phase plus the default binding space
-   a pair whose [car](pairs.html#%28def._%28%28quote._~23~25kernel%29._car%29%29) is a phase and whose [cdr](pairs.html#%28def._%28%28quote._~23~25kernel%29._cdr%29%29) is a non-#f space (in the sense of [space?](#%28def._%28%28lib._racket%2Fphase%2Bspace..rkt%29._space~3f%29%29))
> ```
(phase+space phase space)  →  phase+space?
  phase : phase?
  space : space?
```

Returns a value to represent the combination of phase and space.

> ```
(phase+space-phase p+s)  →  phase?
  p+s : phase+space?

(phase+space-space p+s)  →  phase?
  p+s : phase+space?
```
Extracts the [phase level](syntax-model.html#%28tech._phase._level%29) or [binding space](syntax-model.html#%28tech._binding._space%29) component from a combination.
> ```
(phase+space-shift? v)  →  boolean?
  v : any/c


# 12.10 Serializing Syntax
```
Returns #t if v is a valid representation of a phase level shift and binding space shift combination, #f otherwise. A shift can be applied to a combination of a phase level and binding space using phase+shift+. The possible representations of a shift are as follows:

-  exact integer — represents an amount to shift a phase level and no change to the binding space

-  #f — represents a shift to the label phase level and no change to the binding space

-  a pair whose car is an exact integer or #f, and whose cdr is a space (in the sense of space?) — represents a phase level shift in the car and a change to the binding space that is in the cdr

> ```
(phase+space+ p+s shift)   →   phase+space?
  p+s : phase+space?
  shift : phase+space-shift?```

Applies shift to p+s to produce a new combination of [phase level](syntax-model.html#%28tech._phase._level%29) and [binding space](syntax-model.html#%28tech._binding._space%29).

> ```
(phase+space-shift+ shift additional-shift)  →  phase+space-shift?
  shift : phase+space?
  additional-shift : phase+space-shift?
```
(current-locale)	→
(-> In particular, setting the LC_ALL and LC_CTYPE environment variables does not affect the locale "" on Mac OS. Use getenv and current-locale to explicitly install the environment-specified locale, if desired.)
(current-locale locale) → void?
    locale	:
(-> In particular, setting the LC_ALL and LC_CTYPE environment variables does not affect the locale "" on Mac OS. Use getenv and current-locale to explicitly install the environment-specified locale, if desired.)```


# 12.10 Serializing Syntax
A [parameter](eval-model.html#%28tech._parameter%29) that determines the current [locale](#%28tech._locale%29) for procedures such as [string-locale-ci=?](strings.html#%28def._%28%28quote._~23~25kernel%29._string-locale-ci~3d~3f%29%29).
When locale sensitivity is disabled by setting the parameter to #f, strings are compared, etc., in a fully portable manner, which is the same as the standard procedures. Otherwise, strings are interpreted according to a locale setting (in the sense of the C library’s setlocale). The "" locale is always an alias for the current machine’s default locale, and it is the default. The "C" locale is also always available; setting the locale to "C" is the same as disabling locale sensitivity with #f only when string operations are restricted to the first 128 characters. Other locale names are platform-specific.
String or character printing with [write](Writing.html#%28def._%28%28quote._~23~25kernel%29._write%29%29) is not affected by the parameter, and neither are symbol case or regular expressions (see [Regular Expressions](regexp.html)).
------------------------------------------------------------------------


# 13.1.2 Managing Ports


#### 13.1.2 Managing Ports
> ```
(input-port? v)  →  boolean?
  v : any/c
```
Returns #t if v is an input port, #f otherwise.

> ```
(output-port? v)   →   boolean?
  v : any/c```

Returns #t if v is an [output port](ports.html#%28tech._output._port%29), #f otherwise.

> ```
(port? v)  →  boolean?
  v : any/c
```
(parameter)	→```
Closes the input port in. For some kinds of ports, closing the port releases lower-level resources, such as a file handle. If the port is already closed, [close-input-port](#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29) has no effect.
> ```
(parameter)	→
```
Closes the output port out. For some kinds of ports, closing the port releases lower-level resources, such as a file handle. Also, if the port is buffered, closing may first flush the port before closing it, and this flushing process can block. If the port is already closed, close-output-port has no effect.

> ```
(port-closed? port)   →   boolean?
  port : port?```

Returns #t if the input or output port port is closed, #f otherwise.

> ```
(port-closed-evt port)  →  evt?
  port : port?
```
(current-input-port)	→
(-> current-input-port in)
(current-input-port in) → void?
    in	:
(-> current-input-port in)```
A [parameter](eval-model.html#%28tech._parameter%29) that determines a default input port for many operations, such as [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29).
> ```
(current-output-port)	→
(-> current-output-port out)
(current-output-port out) → void?
    out	:
(-> current-output-port out)


# 13.1.2 Managing Ports
```
(current-error-port)	→
(-> current-error-port out)
(current-error-port out) → void?
    out	:
(-> current-error-port out)```

A [parameter](eval-model.html#%28tech._parameter%29) that determines an output port that is typically used for errors and logging. For example, the default error display handler writes to this port.

> ```
(file-stream-port? v)  →  boolean?
  v : any/c
```
Returns #t if v is a file-stream port (see File Ports), #f otherwise.
Changed in version 7.2.0.5 of package base: Extended file-stream-port? to any value, instead of resticting the domain to ports
> ```
(terminal-port? v)   →   boolean?
  v : any/c```
Returns #t if v is a port that is attached to an interactive terminal, #f otherwise.
Changed in version 7.2.0.5 of package base: Extended [terminal-port?](#%28def._%28%28quote._~23~25kernel%29._terminal-port~3f%29%29) to any value, instead of resticting the domain to ports
> ```
(port-waiting-peer? port)  →  boolean?
  port : port?


# 13.1.2 Managing Ports
```
Returns #t if port is not ready for reading or writing because it is waiting for a peer process to complete a stream construction, #f otherwise.

On Unix and Mac OS, opening a fifo for output creates a peer-waiting port if no reader for the same fifo is already opened. In that case, the output port is not ready for writing until a reader is opened; that is, write opertaions will block. Use sync if necessary to wait until writing will not block—that is, until the read end of the fifo is opened.

Added in version 7.4.0.5 of package base.

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

<p>value</p>

<p>eof : eof-object?</p></blockquote></td></tr></tbody></table>

A value (distinct from all other values) that represents an end-of-file.

> ```
(eof-object? v) → boolean?
  v : any/c```

Returns #t if v is [eof](#%28def._%28%28quote._~23~25kernel%29._eof%29%29), #f otherwise.

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

# 13.1.3 Port Buffers and Positions

#### 13.1.3 Port Buffers and Positions

Some ports—especially those that read from and write to files—are internally buffered:

-   An input port is typically block-buffered by default, which means that on any read, the buffer is filled with immediately-available bytes to speed up future reads. Thus, if a file is modified between a pair of reads to the file, the second read can produce stale data. Calling [file-position](#%28def._%28%28quote._~23~25kernel%29._file-position%29%29) to set an input port’s file position flushes its buffer.

-   An output port is typically block-buffered by default, though a terminal output port is line-buffered, and the initial error output port is unbuffered. An output buffer is filled with a sequence of written bytes to be committed as a group, either when the buffer is full (in block mode), when a newline is written (in line mode), when the port is closed via [close-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29), or when a flush is explicitly requested via a procedure like [flush-output](#%28def._%28%28quote._~23~25kernel%29._flush-output%29%29).

If a port supports buffering, its buffer mode can be changed via [file-stream-buffer-mode](#%28def._%28%28quote._~23~25kernel%29._file-stream-buffer-mode%29%29) (even if the port is not a [file-stream port](file-ports.html#%28tech._file._stream._port%29)).

For an input port, peeking always places peeked bytes into the port’s buffer, even when the port’s buffer mode is 'none; furthermore, on some platforms, testing the port for input (via [char-ready?](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._char-ready~3f%29%29) or [sync](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29)) may be implemented with a peek. If an input port’s buffer mode is 'none, then at most one byte is read for [read-bytes-avail!*](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes-avail%21%2A%29%29), [read-bytes-avail!](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes-avail%21%29%29), [peek-bytes-avail!*](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%2A%29%29), or [peek-bytes-avail!](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%29%29); if any bytes are buffered in the port (e.g., to satisfy a previous peek), the procedures may access multiple buffered bytes, but no further bytes are read.

In addition, the initial current output and error ports are automatically flushed when they are terminal ports (see [terminal-port?](port-ops.html#%28def._%28%28quote._~23~25kernel%29._terminal-port~3f%29%29)) and when [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29), [read-line](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-line%29%29), [read-bytes](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes%29%29), [read-string](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-string%29%29), etc., are performed on the initial standard input port. (More precisely, instead of [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29), flushing is performed by the default port read handler; see [port-read-handler](Reading.html#%28def._%28%28quote._~23~25kernel%29._port-read-handler%29%29).)

> ```
(current-output-port)	→
(-> current-output-port)
```


# 13.1.2 Managing Ports
(parameter)	→
(-> or/c 'none 'line 'block #f)```
Gets or sets the buffer mode for port, if possible. [File-stream ports](file-ports.html#%28tech._file._stream._port%29) support setting the buffer mode, TCP ports (see [Networking](networking.html)) support setting and getting the buffer mode, and custom ports (see [Custom Ports](customport.html)) may support getting and setting buffer modes.
If mode is provided, it must be one of 'none, 'line (output only), or 'block, and the port’s buffering is set accordingly. If the port does not support setting the mode, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised.
If mode is not provided, the current mode is returned, or #f is returned if the mode cannot be determined. If port is an input port and mode is 'line, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.
> ```
(parameter)	→
(-> file-position port pos)


# 13.1.2 Managing Ports
```
Returns or sets the current read/write position of port.

Calling file-position without a position on a port other than a file-stream port or string port returns the number of bytes that have been read from that port if the position is known (see Counting Positions, Lines, and Columns), otherwise the exn:fail:filesystem exception is raised.

For file-stream ports and string ports, the position-setting variant sets the read/write position to pos relative to the beginning of the file or (byte) string if pos is a number, or to the current end of the file or (byte) string if pos is eof. In position-setting mode, file-position raises the exn:fail:contract exception for port kinds other than file-stream ports and string ports. Furthermore, not all file-stream ports support setting the position; if file-position is called with a position argument on such a file-stream port, the exn:fail:filesystem exception is raised.

When file-position sets the position pos beyond the current size of an output file or (byte) string, the file/string is enlarged to size pos and the new region is filled with 0 bytes; in the case of a file. In the case of a file output port, the file might not be enlarged until more data is written to the file; in that case, beware that writing to a file opened in 'append mode on Unix and Mac OS will reset the file pointer to the end of a file before each write, which defeats file enlargement via file-position. If pos is beyond the end of an input file or (byte) string, then reading thereafter returns eof without changing the port’s position.

When changing the file position for an output port, the port is first flushed if its buffer is not empty. Similarly, setting the position for an input port clears the port’s buffer (even if the new position is the same as the old position). However, although input and output ports produced by open-input-output-file share the file position, setting the position via one port does not flush the other port’s buffer.

> ```
(file-position* port)   →   (or/c exact-nonnegative-integer? #f)
  port : port?```

Like [file-position](#%28def._%28%28quote._~23~25kernel%29._file-position%29%29) on a single argument, but returns #f if the position is not known.

> ```
(parameter)	→
(-> and/c output-port? file-stream-port?)
```


# 13.1.2 Managing Ports
(parameter)	→```
Turns on [line location](#%28tech._line._location%29) and [column location](#%28tech._column._location%29) counting for a port. Counting can be turned on at any time, though generally it is turned on before any data is read from or written to a port. At the point that line counting is turned on, [port-next-location](#%28def._%28%28quote._~23~25kernel%29._port-next-location%29%29) typically starts reporting as its last result (one more than) the number of characters read since line counting was enabled, instead of (one more than) bytes read since the port was opened.
When a port is created, if the value of the [port-count-lines-enabled](#%28def._%28%28quote._~23~25kernel%29._port-count-lines-enabled%29%29) parameter is true, then line counting is automatically enabled for the port. Line counting cannot be disabled for a port after it is enabled.
> ```
(port-counts-lines? port)  →  boolean?
  port : port?


# 13.1.2 Managing Ports
```
Returns #t if line location and column location counting has been enabled for port, #f otherwise.

> ```
(port-next-location port)
   →    (or/c exact-positive-integer? #f)
(or/c exact-nonnegative-integer? #f)
(or/c exact-positive-integer? #f)

  port : port?```

Returns three values: an integer or #f for the line number of the next read/written item, an integer or #f for the next item’s column, and an integer or #f for the next item’s position. The next column and position normally increase as bytes are read from or written to the port, but if line/character counting is enabled for port, the column and position results can decrease after reading or writing a byte that ends a UTF-8 encoding sequence.

If line counting is not enabled for a port, than the first two results are #f, and the last result is one more than the number of bytes read so far. At the point when line counting is enabled, the first two results typically become non-#f, and last result starts reporting characters instead of bytes, typically starting from the point when line counting is enabled.

Even with line counting enabled, a port may return #f values if it somehow cannot keep track of lines, columns, or positions.

> ```
(parameter)	→
(-> or/c exact-positive-integer? #f)
```
Sets the next line, column, and position for port. If line counting has not been enabled for port or if port is a custom port that defines its own counting function, then set-port-next-location! has no effect.
> ```
(port-count-lines-enabled)	 →
(  →  port-count-lines-enabled on?)```


# 13.1.2 Managing Ports
A [parameter](eval-model.html#%28tech._parameter%29) that determines whether line counting is enabled automatically for newly created ports. The default value is #f.
------------------------------------------------------------------------


# 13.1.5 File Ports


#### 13.1.5 File Ports
A port created by [open-input-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29), [open-output-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29), [subprocess](subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29), and related functions is a file-stream port. The initial input, output, and error ports in racket are also file-stream ports. The [file-stream-port?](port-ops.html#%28def._%28%28quote._~23~25kernel%29._file-stream-port~3f%29%29) predicate recognizes file-stream ports.
When an input or output file-stream port is created, it is placed into the management of the current custodian (see [Custodians](custodians.html)). In the case of an output port, a [flush callback](plumbers.html#%28tech._flush._callback%29) is registered with the [current plumber](plumbers.html#%28tech._current._plumber%29) to flush the port.
> ```
(open-input-file path
   [ #:mode mode-flag
    #:for-module? for-module?)    →    input-port?
  path : path-string?
  mode-flag : (or/c 'binary 'text) = 'binary
  for-module? : any/c = #f


# 13.1.5 File Ports
```
(otherwise)	→
(-> or/c 'binary 'text)```

Opens the file specified by path for output. The mode-flag argument specifies how bytes written to the port are translated when written to the file:

-   'binary — bytes are written to the file exactly as written to the port.

-   'text — on Windows, a linefeed byte (10) written to the port is translated to a return-linefeed combination in the file; no filtering occurs for returns.

On Windows, 'text mode works only with regular files; attempting to use 'text with other kinds of files triggers an [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception.

The exists-flag argument specifies how to handle/require files that already exist:

-   'error — raise [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) if the file exists.

-   'replace — remove the old file, if it exists, and write a new one.

-   'truncate — remove all old data, if the file exists.

-   'must-truncate — remove all old data in an existing file; if the file does not exist, the [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception is raised.

-   'truncate/replace — try 'truncate; if it fails (perhaps due to file permissions), try 'replace.

-   'update — open an existing file without truncating it; if the file does not exist, the [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception is raised. Use [file-position](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-position%29%29) to change the current read/write position.

-   'can-update — open an existing file without truncating it, or create the file if it does not exist.

-   'append — append to the end of the file, whether it already exists or not; on Windows, 'append is equivalent to 'update, except that the file is not required to exist, and the file position is immediately set to the end of the file after opening it.

When the file specified by path is created, permissions specifies the permissions of the created file, where an integer representation of permissions is treated the same as for [file-or-directory-permissions](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29). On Unix and Mac OS, these permissions bits are combined with the process’s umask. On Windows, the only relevant property of permissions is whether it has the #o2 bit set for write permission. Note that a read-only file can be created with [open-output-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29), in which case writing is prohibited only for later attempts to open the file. If replace-permissions? is a true value, then independent of whether the opened file is newly created, the value of permissions is applied to the opened file, and it is applied independent of the process’s umask on Unix and Mac OS.

The file specified by path need not be a regular file. It might be a device that is connected through the filesystem, such as "aux" on Windows or "/dev/null" on Unix. The output port is block-buffered by default, unless the file corresponds to a terminal, in which case it is line-buffered by default. On Unix and Mac OS, if the file is a fifo, then the port will block for writing until a reader for the fifo is available; see also [port-waiting-peer?](port-ops.html#%28def._%28%28quote._~23~25kernel%29._port-waiting-peer~3f%29%29).

The port produced by [open-output-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29) should be explicitly closed, either though [close-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29) or indirectly via [custodian-shutdown-all](custodians.html#%28def._%28%28quote._~23~25kernel%29._custodian-shutdown-all%29%29), to release the OS-level file handle. The output port will not be closed automatically even if it is otherwise available for garbage collection (see [Garbage Collection](eval-model.html#%28part._gc-model%29)); a [will](willexecutor.html#%28tech._will%29) could be associated with an output port to close it more automatically (see [Wills and Executors](willexecutor.html)).

A [path](pathutils.html#%28tech._path%29) value that is the [cleanse](pathutils.html#%28tech._cleanse%29)d version of path is used as the name of the opened port.

On variants of Unix and MacOS that support O_CLOEXEC, the file is opened with O_CLOEXEC so that the underlying file descriptor is not shared with a subprocess created by [subprocess](subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29). On Windows, the file is opened as a non-inherited handle.

If opening the file fails due to an error in the underlying filesystem then [exn:fail:filesystem:errno](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3aerrno%29%29) exception is raised.

Examples:

> ```racket
> > ( define out ( open-output-file some-file ) )
> > ( write "hello world" out )
> > ( close-output-port out )
> ```

Changed in version 6.9.0.6 of package base: On Unix and Mac OS, make 'truncate/replace replace on a permission error. On Windows, make 'replace always replace instead truncating like 'truncate/replace.
Changed in version 7.4.0.5: Changed handling of a fifo on Unix and Mac OS to make the port block for output until the fifo has a reader.
Changed in version 8.1.0.3: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.
Changed in version 8.11.1.6: Changed to use O_CLOEXEC where supported by the operating system.

> ```
(open-input-output-file
    path
   [ #:mode mode-flag
    #:exists exists-flag
    #:permissions permissions]
    #:replace-permissions? replace-permissions?)

   →    input-port?   output-port?

  path : path-string?
  mode-flag : (or/c 'binary 'text) = 'binary
   exists-flag   :   ( or/c ' error ' append ' update ' can-update
> ' replace ' truncate
> ' must-truncate ' truncate/replace )
      =   'error

  permissions : (integer-in 0 65535) = #o666
  replace-permissions? : #f
```


# 13.1.5 File Ports
Like open-output-file, but producing two values: an input port and an output port. The two ports are connected in that they share the underlying file descriptor. This procedure is intended for use with special devices that can be opened by only one process, such as "COM1" in Windows. For regular files, sharing the file descriptor can be confusing. For example, using one port does not automatically flush the other port’s buffer, and reading or writing in one port moves the file position (if any) for the other port. For regular files, use separate open-input-file and open-output-file calls to avoid confusion.
Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.
> ```
(call-with-input-file path
    proc
   [ #:mode mode-flag)    →    any
  path : path-string?
  proc : (input-port? .  →  . any)
  mode-flag : (or/c 'binary 'text) = 'binary```
Calls [open-input-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29) with the path and mode-flag arguments, and passes the resulting port to proc. The result of proc is the result of the [call-with-input-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._call-with-input-file%29%29) call, but the newly opened port is closed when proc returns.
Examples:
> ```racket
> > ( with-output-to-file some-file ( lambda ( ) ( printf "text in a file" ) ) )
> > ( call-with-input-file some-file ( lambda ( in ) ( read-string 14 in ) ) )
> "text in a file"
> ```
> ```


# 13.1.5 File Ports
(call-with-output-file
    path
    proc
   [ #:mode mode-flag
    #:exists exists-flag
    #:permissions permissions]
    #:replace-permissions? replace-permissions?)
  →  any
  path : path-string?
  proc : (output-port? .  →  . any)
  mode-flag : (or/c 'binary 'text) = 'binary
   exists-flag   :   ( or/c ' error ' append ' update ' can-update
> ' replace ' truncate
> ' must-truncate ' truncate/replace )
      =   'error
  permissions : (integer-in 0 65535) = #o666
  replace-permissions? : #f
```
Analogous to call-with-input-file, but passing path, mode-flag, exists-flag, and permissions to open-output-file.

Examples:

> ```racket
> > ( call-with-output-file some-file ( lambda ( out ) ( write ' hello out ) ) )
> > ( call-with-input-file some-file ( lambda ( in ) ( read-string 5 in ) ) )
> "hello"
> ```

Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

> ```
(call-with-input-file* path
    proc
   [ #:mode mode-flag)    →    any

  path : path-string?
  proc : (input-port? .  →  . any)
  mode-flag : (or/c 'binary 'text) = 'binary```

Like [call-with-input-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._call-with-input-file%29%29), but the newly opened port is closed whenever control escapes the dynamic extent of the [call-with-input-file*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._call-with-input-file%2A%29%29) call, whether through proc’s return, a continuation application, or a prompt-based abort.

> ```
(call-with-output-file*
    path
    proc
   [ #:mode mode-flag
    #:exists exists-flag
    #:permissions permissions]
    #:replace-permissions? replace-permissions?)

  →  any
  path : path-string?
  proc : (output-port? .  →  . any)
  mode-flag : (or/c 'binary 'text) = 'binary
   exists-flag   :   ( or/c ' error ' append ' update ' can-update
> ' replace ' truncate
> ' must-truncate ' truncate/replace )
      =   'error

  permissions : (integer-in 0 65535) = #o666
  replace-permissions? : #f
```


# 13.1.5 File Ports
Like call-with-output-file, but the newly opened port is closed whenever control escapes the dynamic extent of the call-with-output-file* call, whether through proc’s return, a continuation application, or a prompt-based abort.
Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.
> ```
(with-input-from-file path
    thunk
   [ #:mode mode-flag)    →    any
  path : path-string?
  thunk : (  →   any)
  mode-flag : (or/c 'binary 'text) = 'binary```
Like [call-with-input-file*](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._call-with-input-file%2A%29%29), but instead of passing the newly opened port to the given procedure argument, the port is installed as the current input port (see [current-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29)) using [parameterize](parameters.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29) around the call to thunk.
Examples:
> ```racket
> > ( with-output-to-file some-file ( lambda ( ) ( printf "hello" ) ) )
> > ( with-input-from-file some-file ( lambda ( ) ( read-string 5 ) ) )
> "hello"
> ```
> ```
(with-output-to-file
    path
    thunk
   [ #:mode mode-flag
    #:exists exists-flag
    #:permissions permissions]
    #:replace-permissions? replace-permissions?)
  →  any
  path : path-string?
  thunk : (  →   any)
  mode-flag : (or/c 'binary 'text) = 'binary
   exists-flag   :   ( or/c ' error ' append ' update ' can-update


# 13.1.5 File Ports
> ' replace ' truncate
> ' must-truncate ' truncate/replace )
      =   'error
  permissions : (integer-in 0 65535) = #o666
  replace-permissions? : #f
```
(parameter)	→
(-> or/c 'shared 'exclusive)```

Attempts to acquire a lock on the file using the current platform’s facilities for file locking. Multiple processes can acquire a 'shared lock on a file, but at most one process can hold an 'exclusive lock, and 'shared and 'exclusive locks are mutually exclusive. When mode is 'shared, then port must be an input port; when mode is 'exclusive, then port must be an output port.

The result is #t if the requested lock is acquired, #f otherwise. When a lock is acquired, it is held until either it is released with [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) or the port is closed (perhaps because the process terminates).

Depending on the platform, locks may be merely advisory (i.e., locks affect only the ability of processes to acquire locks) or they may correspond to mandatory locks that prevent reads and writes to the locked file. Specifically, locks are mandatory on Windows and advisory on other platforms. Multiple tries for a 'shared lock on a single port can succeed; on Unix and Mac OS, a single [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) release the lock, while on other Windows, a [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) is needed for each successful [port-try-file-lock?](#%28def._%28%28quote._~23~25kernel%29._port-try-file-lock~3f%29%29). On Unix and Mac OS, multiple tries for a 'exclusive lock can succeed and a single [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) releases the lock, while on Windows, a try for an 'exclusive lock fails for a given port if the port already holds the lock.

A lock acquired for an input port from [open-input-output-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-output-file%29%29) can be released through [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) on the corresponding output port, and vice versa. If the output port from [open-input-output-file](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-output-file%29%29) holds an 'exclusive lock, the corresponding input port can still acquire a 'shared lock, even multiple times; on Windows, a [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) is needed for each successful lock try, while a single [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) balances the lock tries on Unix and Mac OS. A 'shared lock on an input port can be upgraded to an 'exclusive lock through the corresponding output port on Unix and Mac OS, in which case a single [port-file-unlock](#%28def._%28%28quote._~23~25kernel%29._port-file-unlock%29%29) (on either port) releases the lock, while such upgrades are not allowed on Windows.

Locking is normally supported only for file ports, and attempting to acquire a lock with other kinds of file-stream ports raises an [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception.

> ```
(parameter)	→
```


# 13.1.5 File Ports
Releases a lock held by the current process on the file of port.
> ```
(port-file-identity port)  →  exact-positive-integer?
  port : file-stream-port?
```

Returns a number that represents the identity of the device and file read or written by port. For two ports whose open times overlap, the result of [port-file-identity](#%28def._%28%28quote._~23~25kernel%29._port-file-identity%29%29) is the same for both ports if and only if the ports access the same device and file. For ports whose open times do not overlap, no guarantee can be provided for the port identities (even if the ports actually access the same file)—except as can be inferred through relationships with other ports. If port is closed, the [exn:fail](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) exception is raised. On Windows 95, 98, and Me, if port is connected to a pipe instead of a file, the [exn:fail:filesystem](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) exception is raised.

Examples:

> ```racket
> > ( define file1 ( open-output-file some-file ) )
> > ( define file2 ( open-output-file some-other-file ) )
> > ( port-file-identity file1 )
> 358412864794394642
> > ( port-file-identity file2 )
> 358412869089361938
> > ( close-output-port file1 )
> > ( close-output-port file2 )
> ```

> ```
(parameter)	→
(-> and/c (hash/c symbol? any/c) hash-eq?)
```
Like file-or-directory-stat, but returns information for an open file represented by a port, instead using of the file’s path.


# 13.1.5 File Ports
Added in version 8.15.0.6 of package base.
------------------------------------------------------------------------


# 13.1.6 String Ports


#### 13.1.6 String Ports
A string port reads or writes from a byte string. An input string port can be created from either a byte string or a string; in the latter case, the string is effectively converted to a byte string using string  →  bytes/utf-8. An output string port collects output into a byte string, but get-output-string conveniently converts the accumulated bytes to a string.
Input and output string ports do not need to be explicitly closed. The file-position procedure works for string ports in position-setting mode.
> > > <img src="magnify.png" width="24" height="24" alt="+" />Byte Strings also provides information on bytestrings.
> ```
(string-port? p) → boolean?
  p : port?```
Returns #t if p is a [string port](#%28tech._string._port%29), #f otherwise.
Added in version 6.0.1.6 of package base.
> ```
(open-input-bytes bstr [name) → (and/c input-port? string-port?)
  bstr : bytes?
  name : any/c = 'string


# 13.1.6 String Ports
```
Creates an input string port that reads characters from bstr (see Byte Strings). Modifying bstr afterward does not affect the byte stream produced by the port. The optional name argument is used as the name for the returned port.

Examples:

> ```racket
> > ( define sp ( open-input-bytes #"(apples 42 day)" ) )
> > ( define sexp1 ( read sp ) )
> > ( first sexp1 )
> 'apples
> > ( rest sexp1 )
> '(42 day)
> > ( read-line ( open-input-bytes #"the cow jumped over the moon\nthe little dog\n" ) )
> "the cow jumped over the moon"
> ```

> > > <img src="magnify.png" width="24" height="24" alt="+" />Strings also provides information on strings.

> ```
(open-input-string str [name) → (and/c input-port? string-port?)
  str : string?
  name : any/c = 'string```

Creates an input [string port](#%28tech._string._port%29) that reads bytes from the UTF-8 encoding (see [Encodings and Locales](encodings.html)) of str. The optional name argument is used as the name for the returned port.

Examples:

> ```racket
> > ( define sp ( open-input-string "(λ (x) x)" ) )
> > ( read sp )
> '(λ (x) x)
> > ( define names ( open-input-string "Günter Harder\nFrédéric Paulin\n" ) )
> > ( read-line names )
> "Günter Harder"
> > ( read-line names )
> "Frédéric Paulin"
> ```

> ```
(open-output-bytes [name) → (and/c output-port? string-port?)
  name : any/c = 'string
```
Creates an output string port that accumulates the output into a byte string. The optional name argument is used as the name for the returned port.
Examples:


# 13.1.6 String Ports
> ```racket
> > ( define op1 ( open-output-bytes ) )
> > ( write ' ( ( 1 2 3 ) ( "Tom" "Dick" ) ( ' a ' b ' c ) ) op1 )
> > ( get-output-bytes op1 )
> #"((1 2 3) (\"Tom\" \"Dick\") ((quote a) (quote b) (quote c)))"
> > ( define op2 ( open-output-bytes ) )
> > ( write "Hi " op2 )
> > ( write "there" op2 )
> > ( get-output-bytes op2 )
> #"\"Hi \"\"there\""
> > ( define op3 ( open-output-bytes ) )
> > ( write-bytes #"Hi " op3 )
> 3
> > ( write-bytes #"there" op3 )
> 5
> > ( get-output-bytes op3 )
> #"Hi there"
> ```
> ```
(open-output-string [name) → (and/c output-port? string-port?)
  name : any/c = 'string```
The same as [open-output-bytes](#%28def._%28%28quote._~23~25kernel%29._open-output-bytes%29%29).
Examples:
> ```racket
> > ( define op1 ( open-output-string ) )
> > ( write ' ( ( 1 2 3 ) ( "Tom" "Dick" ) ( ' a ' b ' c ) ) op1 )
> > ( get-output-string op1 )
> "((1 2 3) (\"Tom\" \"Dick\") ((quote a) (quote b) (quote c)))"
> > ( define op2 ( open-output-string ) )
> > ( write "Hi " op2 )
> > ( write "there" op2 )
> > ( get-output-string op2 )
> "\"Hi \"\"there\""
> > ( define op3 ( open-output-string ) )
> > ( write-string "Hi " op3 )
> 3
> > ( write-string "there" op3 )
> 5
> > ( get-output-string op3 )
> "Hi there"
> ```
> ```
(get-output-bytes out
   [ reset?
    start-pos
    end-pos)    →    bytes?
  out : (and/c output-port? string-port?)
  reset? : any/c = #f
  start-pos : exact-nonnegative-integer? = 0
  end-pos : exact-nonnegative-integer? = #f


# 13.1.6 String Ports
```
Returns the bytes accumulated in the string port out so far in a freshly allocated byte string (including any bytes written after the port’s current position, if any). The out port must be an output string port produced by open-output-bytes (or open-output-string) or a structure whose prop:output-port property refers to such an output port (transitively).

If reset? is true, then all bytes are removed from the port, and the port’s position is reset to 0; if reset? is #f, then all bytes remain in the port for further accumulation (so they are returned for later calls to get-output-bytes or get-output-string), and the port’s position is unchanged.

The start-pos and end-pos arguments specify the range of bytes in the port to return; supplying start-pos and end-pos is the same as using subbytes on the result of get-output-bytes, but supplying them to get-output-bytes can avoid an allocation. The end-pos argument can be #f, which corresponds to not passing a second argument to subbytes.

Examples:

> ```racket
> > ( define op ( open-output-bytes ) )
> > ( write ' ( ( 1 2 3 ) ( "Tom" "Dick" ) ( ' a ' b ' c ) ) op )
> > ( get-output-bytes op )
> #"((1 2 3) (\"Tom\" \"Dick\") ((quote a) (quote b) (quote c)))"
> > ( get-output-bytes op #f 3 16 )
> #" 2 3) (\"Tom\" "
> > ( get-output-bytes op #t )
> #"((1 2 3) (\"Tom\" \"Dick\") ((quote a) (quote b) (quote c)))"
> > ( get-output-bytes op )
> #""
> ```

> ```
(get-output-string out)   →   string?
  out : (and/c output-port? string-port?)```

Returns ([bytes->string/utf-8](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes-~3estring%2Futf-8%29%29) ([get-output-bytes](#%28def._%28%28quote._~23~25kernel%29._get-output-bytes%29%29) out) #\\uFFFD).

Examples:

> ```racket
> > ( define i ( open-input-string "hello world" ) )
> > ( define o ( open-output-string ) )
> > ( write ( read i ) o )
> > ( get-output-string o )
> "hello"
> ```

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

# 13.1.7 Pipes

#### 13.1.7 Pipes

A Racket pipe is internal to Racket, and not related to OS-level pipes for communicating between different processes.OS-level pipes may be created by [subprocess](subprocess.html#%28def._%28%28quote._~23~25kernel%29._subprocess%29%29), opening an existing named file on a Unix filesystem, or starting Racket with pipes for its original input, output, or error port. Such pipes are [file-stream ports](file-ports.html#%28tech._file._stream._port%29), unlike the pipes produced by [make-pipe](#%28def._%28%28quote._~23~25kernel%29._make-pipe%29%29).

> ```
(pipe-port? p)  →  boolean?
  p : port?
```


# 13.1.6 String Ports
Returns #t if p is either end of a pipe created by make-pipe, #f otherwise.
Added in version 8.15.0.9 of package base.
> ```
(make-pipe [limit input-name output-name)
   →    (and/c input-port? pipe-port?)
(and/c output-port? pipe-port?)
  limit : exact-positive-integer? = #f
  input-name : any/c = 'pipe
  output-name : any/c = 'pipe```
Returns two port values: the first port is an input port and the second is an output port. Data written to the output port is read from the input port, with no intermediate buffering. Unlike some other kinds of ports, pipe ports do not need to be explicitly closed to be reclaimed by [garbage collection](eval-model.html#%28part._gc-model%29).
If limit is #f, the new pipe holds an unlimited number of unread bytes (i.e., limited only by the available memory). If limit is a positive number, then the pipe will hold at most limit unread/unpeeked bytes; writing to the pipe’s output port thereafter will block until a read or peek from the input port makes more space available. (Peeks effectively extend the port’s capacity until the peeked bytes are read.)
The optional input-name and output-name are used as the names for the returned input and output ports, respectively.
> ```
(pipe-content-length pipe-port)  →  exact-nonnegative-integer?
  pipe-port : pipe-port?