# 13.1.6 String Ports
```
Returns the number of bytes contained in a pipe, where pipe-port is either of the pipe’s ports produced by make-pipe. The pipe’s content length counts all bytes that have been written to the pipe and not yet read (though possibly peeked).

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

# 13.1.8 Structures as Ports

#### 13.1.8 Structures as Ports

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

<p>value</p>

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

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

<p>value</p>

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

The prop:input-port and prop:output-port structure type properties identify structure types whose instances can serve as input and output ports, respectively.

Each property value can be either of the following:

-  An input port (for prop:input-port) or output port (for prop:output-port): In this case, using the structure as port is equivalent to using the given input or output port.

-  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. If the field contains an input port (for prop:input-port) or output port (for prop:output-port), the port is used. Otherwise, an empty string input port is used for prop:input-port, and a port that discards all data is used for prop:output-port.

Some procedures, such as file-position, work on both input and output ports. When given an instance of a structure type with both the prop:input-port and prop:output-port properties, the instance is used as an input port.

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

# 13.1.9 Custom Ports

#### 13.1.9 Custom Ports

The make-input-port and make-output-port procedures create custom ports with arbitrary control procedures (much like implementing a device driver). Custom ports are mainly useful to obtain fine control over the action of committing bytes as read or written.

> ```
(make-input-port name
    read-in
    peek
    close
   [ get-progress-evt
    commit
    get-location
    count-lines!
    init-position
    buffer-mode)    →    input-port?

  name : any/c
   read-in   :   ( or/c
> ( bytes?
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt? ) )
> input-port? )

   peek   :   ( or/c
> ( bytes? exact-nonnegative-integer? ( or/c evt? #f )
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f ) )
> input-port?
> #f )

  close : (  →   any)
  get-progress-evt : (or/c (  →   evt?) #f) = #f
   commit   :   ( or/c ( exact-positive-integer? evt? evt? .  →  . any )
> #f )
      =   #f

   get-location   :   ( or/c
> (  →
> ( values ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f ) ) )
> #f )
      =   #f

  count-lines! : (  →   any) = void
   init-position   :   ( or/c exact-positive-integer?
> port?
> #f
> (  →  ( or/c exact-positive-integer? #f ) ) )
      =   1

   buffer-mode   :   ( or/c ( case  →  ( ( or/c ' block ' none ) .  →  . any )
> (  →  ( or/c ' block ' none #f ) ) )
> #f )
      =   #f```

Creates an input port, which is immediately open for reading. If close procedure has no side effects, then the port need not be explicitly closed. See also [make-input-port/read-to-peek](port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._make-input-port%2Fread-to-peek%29%29).

The arguments implement the port as follows:

-   name — the name for the input port.

-

    read-in — either an input port, in which case reads are redirected to the given port, or a procedure that takes a single argument: a mutable byte string to receive read bytes. The procedure’s result is one of the following:

    -   the number of bytes read, as an exact, non-negative integer;

    -   [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29);

    -   a procedure of arity four (representing a “special” result, as discussed [further below](#%28elem._special%29)), but a procedure result is allowed only when peek is not #f;

    -   a [pipe](pipeports.html#%28tech._pipe%29) input port that supplies bytes to be used as long as the pipe has content (see [pipe-content-length](pipeports.html#%28def._%28%28quote._~23~25kernel%29._pipe-content-length%29%29)) or until read-in or peek is called again; or

    -   a [synchronizable event](sync.html#%28tech._synchronizable._event%29) (see [Events](sync.html)) other than a pipe input port or procedure of arity four; the event becomes ready when the read is complete (roughly): the event’s value can be one of the above four results or another event like itself; in the last case, a reading process loops with [sync](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%29%29) until it gets a non-event result.

    The read-in procedure must not block indefinitely. If no bytes are immediately available for reading, the read-in must return 0 or an event, and preferably an event (to avoid busy waits). The read-in should not return 0 (or an event whose value is 0) when data is available in the port, otherwise polling the port will behave incorrectly. An event result from an event can also break polling.

    If the result of a read-in call is not one of the above values, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised. If a returned integer is larger than the supplied byte string’s length, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised. If peek is #f and a procedure for a [special](#%28elem._special%29) result is returned, the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

    The read-in procedure can report an error by raising an exception, but only if no bytes are read. Similarly, no bytes should be read if [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29), an event, or a procedure is returned. In other words, no bytes should be lost due to spurious exceptions or non-byte data.

    A port’s reading procedure may be called in multiple threads simultaneously (if the port is accessible in multiple threads), and the port is responsible for its own internal synchronization. Note that improper implementation of such synchronization mechanisms might cause a non-blocking read procedure to block indefinitely.

    If the result is a pipe input port, then previous get-progress-evt calls whose event is not yet ready must have been the pipe input port itself. Furthermore, get-progress-evt must continue to return the pipe as long as it contains data, or until the read-in or peek-in procedure is called again (instead of using the pipe, for whatever reason). If read-in or peek-in is called, any previously associated pipe (as returned by a previous call) is disassociated from the port and is not in use by any other thread as a result of the previous association.

    If peek, get-progress-evt, and commit are all provided and non-#f, then the following is an acceptable implementation of read-in:

    > ```racket
    > ( lambda ( bstr )
    > ( let* ( [ progress-evt ( get-progress-evt ) ]
    > [ v ( peek bstr 0 progress-evt ) ] )
    > ( cond
    > [ ( sync/timeout 0 progress-evt ) 0 ] ; try again
    > [ ( evt? v ) ( wrap-evt v ( lambda ( x ) 0 ) ) ] ; sync, try again
    > [ ( and ( number? v ) ( zero? v ) ) 0 ] ; try again
    > [ else
    > ( if ( commit ( if ( number? v ) v 1 )
    > progress-evt
    > always-evt )
    > v ; got a result
    > 0 ) ] ) ) ) ; try again
    > ```

    An implementor may choose not to implement the peek, get-progress-evt, and commit procedures, however, and even an implementor who does supply them may provide a different read-in that uses a fast path for non-blocking reads.

    In an input port is provided for read-in, then an input port must also be provided for peek.

-   peek — either #f, an input port (in which case peeks are redirected to the given port), or a procedure that takes three arguments:

    -   a mutable byte string to receive peeked bytes;

    -   a non-negative number of bytes (or [specials](#%28elem._special%29)) to skip before peeking; and

    -   either #f or a progress event produced by get-progress-evt.

    The results and conventions for peek are mostly the same as for read-in. The main difference is in the handling of the progress event, if it is not #f. If the given progress event becomes ready, the peek must abort any skip attempts and not peek any values. In particular, peek must not peek any values if the progress event is initially ready. If the port has been closed, the progress event should be ready, in which case peek should complete (instead of failing because the port is closed).

    Unlike read-in, peek should produce #f (or an event whose value is #f) if no bytes were peeked because the progress event became ready. Like read-in, a 0 result indicates that another attempt is likely to succeed, so 0 is inappropriate when the progress event is ready. Also like read-in, peek must not block indefinitely. An event produced by peek is polled (in the sense of [poll-guard-evt](sync.html#%28def._%28%28quote._~23~25kernel%29._poll-guard-evt%29%29)) by an option like [byte-ready?](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._byte-ready~3f%29%29) or peek-bytes-avail\*!.

    The skip count provided to peek is a number of bytes (or [specials](#%28elem._special%29)) that must remain present in the port—in addition to the peek results—when the peek results are reported. If the skip count requests reading data that is past an eof, it should not, and instead produce [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) (until the eof is consumed).

    If a progress event is supplied, then the peek is effectively canceled when another process reads data before the given number can be skipped. If a progress event is not supplied and data is read, then the peek must effectively restart with the original skip count.

    The system does not check that multiple peeks return consistent results, or that peeking and reading produce consistent results, although they must.

    If peek is #f, then peeking for the port is implemented automatically in terms of reads, but with several limitations. First, the automatic implementation is not thread-safe. Second, the automatic implementation cannot handle [special](#%28elem._special%29) results (non-byte and non-eof), so read-in cannot return a procedure for a [special](#%28elem._special%29) when peek is #f. Finally, the automatic peek implementation is incompatible with progress events, so if peek is #f, then get-progress-evt and commit must be #f. See also [make-input-port/read-to-peek](port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._make-input-port%2Fread-to-peek%29%29), which implements peeking in terms of read-in without these constraints.

    In an input port is provided for peek, then an input port must also be provided for read-in.

-   close — a procedure of zero arguments that is called to close the port. The port is not considered closed until the closing procedure returns. The port’s procedures will never be used again via the port after it is closed. However, the closing procedure can be called simultaneously in multiple threads (if the port is accessible in multiple threads), and it may be called during a call to the other procedures in another thread; in the latter case, any outstanding reads and peeks should be terminated with an error.

-   get-progress-evt — either #f (the default), or a procedure that takes no arguments and returns an event. The event must become ready only after data is next read from the port or the port is closed. If the port is already closed, the event must be ready. After the event becomes ready, it must remain so. See the description of read-in for information about the allowed results of this function when read-in returns a pipe input port. See also [semaphore-peek-evt](semaphore.html#%28def._%28%28quote._~23~25kernel%29._semaphore-peek-evt%29%29), which is sometimes useful for implementing get-progress-evt.

    If get-progress-evt is #f, then [port-provides-progress-evts?](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._port-provides-progress-evts~3f%29%29) applied to the port will produce #f, and the port will not be a valid argument to [port-progress-evt](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._port-progress-evt%29%29).

    The result event will not be exposed directly by [port-progress-evt](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._port-progress-evt%29%29). Instead, it will be wrapped in an event for which [progress-evt?](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._progress-evt~3f%29%29) returns true.

-   commit — either #f (the default), or a procedure that takes three arguments:

    -   an exact, positive integer kr;

    -   a progress event produced by get-progress-evt;

    -   an event, done, that is either a channel-put event, channel, semaphore, semaphore-peek event, always event, or never event.

    A commit corresponds to removing data from the stream that was previously peeked, but only if no other process removed data first. (The removed data does not need to be reported, because it has been peeked already.) More precisely, assuming that kp bytes, [specials](#%28elem._special%29), and mid-stream [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29)s have been previously peeked or skipped at the start of the port’s stream, commit must satisfy the following constraints:

    -   It must return only when the commit is complete or when the given progress event becomes ready.

    -   It must commit only if kp is positive.

    -   If it commits, then it must do so with either kr items or kp items, whichever is smaller, and only if kp is positive.

    -   It must never choose done in a synchronization after the given progress event is ready, or after done has been synchronized once.

    -   It must not treat any data as read from the port unless done is chosen in a synchronization.

    -   It must not block indefinitely if done is ready; it must return soon after the read completes or soon after the given progress event is ready, whichever is first.

    -   It can report an error by raising an exception, but only if no data has been committed. In other words, no data should be lost due to an exception, including a break exception.

    -   It must return a true value if data has been committed, #f otherwise. When it returns a value, the given progress event must be ready (perhaps because data has just been committed).

    -   It should return a byte string as a true result when line counting is enabled and get-location is #f (so that line counting is implemented the default way); the result byte string represents the data that was committed for the purposes of character and line counting. If any other true result is returned when a byte string is expected, it is treated like a byte string where each byte corresponds to a non-newline character.

    -   It must raise an exception if no data (including [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29)) has been peeked from the beginning of the port’s stream, or if it would have to block indefinitely to wait for the given progress event to become ready.

    A call to commit is [parameterize-break](breakhandler.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize-break%29%29)ed to disable breaks.

-   get-location — either #f (the default), or a procedure that takes no arguments and returns three values: the line number for the next item in the port’s stream (a positive number or #f), the column number for the next item in the port’s stream (a non-negative number or #f), and the position for the next item in the port’s stream (a positive number or #f). See also [Counting Positions, Lines, and Columns](linecol.html).

    This procedure is called to implement [port-next-location](linecol.html#%28def._%28%28quote._~23~25kernel%29._port-next-location%29%29), but only if line counting is enabled for the port via [port-count-lines!](linecol.html#%28def._%28%28quote._~23~25kernel%29._port-count-lines%21%29%29) (in which case count-lines! is called). The [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) and [read-syntax](Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) procedures assume that reading a non-whitespace character increments the column and position by one.

-   count-lines! — a procedure of no arguments that is called if and when line counting is enabled for the port. The default procedure is [void](void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29).

-   init-position — normally an exact, positive integer that determines the position of the port’s first item, which is used by [file-position](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-position%29%29) or when line counting is not enabled for the port. The default is 1. If init-position is #f, the port is treated as having an unknown position. If init-position is a port, then the given port’s position is always used for the new port’s position. If init-position is a procedure, it is called as needed to obtain the port’s position.

-   buffer-mode — either #f (the default) or a procedure that accepts zero or one arguments. If buffer-mode is #f, then the resulting port does not support a buffer-mode setting. Otherwise, the procedure is called with one symbol argument ('block or 'none) to set the buffer mode, and it is called with zero arguments to get the current buffer mode. In the latter case, the result must be 'block, 'none, or #f (unknown). See [Port Buffers and Positions](port-buffers.html) for more information on buffer modes.

“Special” results: When read-in or peek (or an event produced by one of these) returns a procedure, the procedure is used to obtain a non-byte result. (This non-byte result is not intended to return a character or [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29); in particular, [read-char](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-char%29%29) raises an exception if it encounters a special-result procedure, even if the procedure produces a byte.) A special-result procedure must accept four arguments that represent a source location. The first argument is #f when the special read is triggered by [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) or [read/recursive](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29).

The special-value procedure can return an arbitrary value, and it will be called zero or one times (not necessarily before further reads or peeks from the port). See [Reader-Extension Procedures](reader-procs.html) for more details on the procedure’s result.

If read-in or peek returns a special procedure when called by any reading procedure other than [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29), [read-syntax](Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29), [read-char-or-special](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-char-or-special%29%29), [peek-char-or-special](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._peek-char-or-special%29%29), [read-byte-or-special](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-byte-or-special%29%29), or [peek-byte-or-special](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._peek-byte-or-special%29%29), then the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

Examples:

> ```racket
> ; A port with no input...
> ; Easy: ( open-input-bytes #"" )
> ; Hard:
> > ( define /dev/null-in ( make-input-port ' null ( lambda ( s ) eof ) ( lambda ( skip s progress-evt ) eof ) void ( lambda ( ) never-evt ) ( lambda ( k progress-evt done-evt ) ( error "no successful peeks!" ) ) ) )
> > ( read-char /dev/null-in )
> #<eof>
> > ( peek-char /dev/null-in )
> #<eof>
> > ( read-byte-or-special /dev/null-in )
> #<eof>
> > ( peek-byte-or-special /dev/null-in 100 )
> #<eof>
> ; A port that produces a stream of 1s:
> > ( define infinite-ones ( make-input-port ' ones ( lambda ( s ) ( bytes-set! s 0 ( char->integer #\1 ) ) 1 ) #f void ) )
> > ( read-string 5 infinite-ones )
> "11111"
> ; But we can ' t peek ahead arbitrarily far, because the
> ; automatic peek must record the skipped bytes, so
> ; we ' d run out of memory.
> ; An infinite stream of 1s with a specific peek procedure:
> > ( define infinite-ones ( let ( [ one! ( lambda ( s ) ( bytes-set! s 0 ( char->integer #\1 ) ) 1 ) ] ) ( make-input-port ' ones one! ( lambda ( s skip progress-evt ) ( one! s ) ) void ) ) )
> > ( read-string 5 infinite-ones )
> "11111"
> ; Now we can peek ahead arbitrarily far:
> > ( peek-string 5 ( expt 2 5000 ) infinite-ones )
> "11111"
> ; The port doesn ' t supply procedures to implement progress events:
> > ( port-provides-progress-evts? infinite-ones )
> #f
> > ( port-progress-evt infinite-ones )
> port-progress-evt: port does not provide progress evts
> port: #<input-port:ones>
> ; Non-byte port results:
> > ( define infinite-voids ( make-input-port ' voids ( lambda ( s ) ( lambda args ' void ) ) ( lambda ( skip s evt ) ( lambda args ' void ) ) void ) )
> > ( read-char infinite-voids )
> read-char: non-character in an unsupported context
> port: #<input-port:voids>
> > ( read-char-or-special infinite-voids )
> 'void
> ; This port produces 0, 1, 2, 0, 1, 2, etc., but it is not
> ; thread-safe, because multiple threads might read and change n .
> > ( define mod3-cycle/one-thread ( let* ( [ n 2 ] [ mod! ( lambda ( s delta ) ( bytes-set! s 0 ( + 48 ( modulo ( + n delta ) 3 ) ) ) 1 ) ] ) ( make-input-port ' mod3-cycle/not-thread-safe ( lambda ( s ) ( set! n ( modulo ( add1 n ) 3 ) ) ( mod! s 0 ) ) ( lambda ( s skip evt ) ( mod! s skip ) ) void ) ) )
> > ( read-string 5 mod3-cycle/one-thread )
> "01201"
> > ( peek-string 5 ( expt 2 5000 ) mod3-cycle/one-thread )
> "20120"
> ; Same thing, but thread-safe and kill-safe, and with progress
> ; events. Only the server thread touches the stateful part
> ; directly. (See the output port examples for a simpler thread-safe
> ; example, but this one is more general.)
> > ( define ( make-mod3-cycle ) ( define read-req-ch ( make-channel ) ) ( define peek-req-ch ( make-channel ) ) ( define progress-req-ch ( make-channel ) ) ( define commit-req-ch ( make-channel ) ) ( define close-req-ch ( make-channel ) ) ( define closed? #f ) ( define n 0 ) ( define progress-sema #f ) ( define ( mod! s delta ) ( bytes-set! s 0 ( + 48 ( modulo ( + n delta ) 3 ) ) ) 1 ) ; — — — — — — — — — — — — — - ; The server has a list of outstanding commit requests, ; and it also must service each port operation (read, ; progress-evt, etc.) ( define ( serve commit-reqs response-evts ) ( apply sync ( handle-evt read-req-ch ( handle-read commit-reqs response-evts ) ) ( handle-evt progress-req-ch ( handle-progress commit-reqs response-evts ) ) ( handle-evt commit-req-ch ( add-commit commit-reqs response-evts ) ) ( handle-evt close-req-ch ( handle-close commit-reqs response-evts ) ) ( append ( map ( make-handle-response commit-reqs response-evts ) response-evts ) ( map ( make-handle-commit commit-reqs response-evts ) commit-reqs ) ) ) ) ; Read/peek request: fill in the string and commit ( define ( ( handle-read commit-reqs response-evts ) r ) ( let ( [ s ( car r ) ] [ skip ( cadr r ) ] [ ch ( caddr r ) ] [ nack ( cadddr r ) ] [ evt ( car ( cddddr r ) ) ] [ peek? ( cdr ( cddddr r ) ) ] ) ( let ( [ fail? ( and evt ( sync/timeout 0 evt ) ) ] ) ( unless ( or closed? fail? ) ( mod! s skip ) ( unless peek? ( commit! 1 ) ) ) ; Add an event to respond: ( serve commit-reqs ( cons ( choice-evt nack ( channel-put-evt ch ( if closed? 0 ( if fail? #f 1 ) ) ) ) response-evts ) ) ) ) ) ; Progress request: send a peek evt for the current ; progress-sema ( define ( ( handle-progress commit-reqs response-evts ) r ) ( let ( [ ch ( car r ) ] [ nack ( cdr r ) ] ) ( unless progress-sema ( set! progress-sema ( make-semaphore ( if closed? 1 0 ) ) ) ) ; Add an event to respond: ( serve commit-reqs ( cons ( choice-evt nack ( channel-put-evt ch ( semaphore-peek-evt progress-sema ) ) ) response-evts ) ) ) ) ; Commit request: add the request to the list ( define ( ( add-commit commit-reqs response-evts ) r ) ( serve ( cons r commit-reqs ) response-evts ) ) ; Commit handling: watch out for progress, in which case ; the response is a commit failure; otherwise, try ; to sync for a commit. In either event, remove the ; request from the list ( define ( ( make-handle-commit commit-reqs response-evts ) r ) ( let ( [ k ( car r ) ] [ progress-evt ( cadr r ) ] [ done-evt ( caddr r ) ] [ ch ( cadddr r ) ] [ nack ( cddddr r ) ] ) ; Note: we don ' t check that k is <= the sum of ; previous peeks, because the entire stream is actually ; known, but we could send an exception in that case. ( choice-evt ( handle-evt progress-evt ( lambda ( x ) ( sync nack ( channel-put-evt ch #f ) ) ( serve ( remq r commit-reqs ) response-evts ) ) ) ; Only create an event to satisfy done-evt if progress-evt ; isn ' t already ready. ; Afterward, if progress-evt becomes ready, then this ; event-making function will be called again, because ; the server controls all posts to progress-evt. ( if ( sync/timeout 0 progress-evt ) never-evt ( handle-evt done-evt ( lambda ( v ) ( commit! k ) ( sync nack ( channel-put-evt ch #t ) ) ( serve ( remq r commit-reqs ) response-evts ) ) ) ) ) ) ) ; Response handling: as soon as the respondee listens, ; remove the response ( define ( ( make-handle-response commit-reqs response-evts ) evt ) ( handle-evt evt ( lambda ( x ) ( serve commit-reqs ( remq evt response-evts ) ) ) ) ) ; Close handling: post the progress sema, if any, and set ; the closed? flag ( define ( ( handle-close commit-reqs response-evts ) r ) ( let ( [ ch ( car r ) ] [ nack ( cdr r ) ] ) ( set! closed? #t ) ( when progress-sema ( semaphore-post progress-sema ) ) ( serve commit-reqs ( cons ( choice-evt nack ( channel-put-evt ch ( void ) ) ) response-evts ) ) ) ) ; Helper for reads and post-peek commits: ( define ( commit! k ) ( when progress-sema ( semaphore-post progress-sema ) ( set! progress-sema #f ) ) ( set! n ( + n k ) ) ) ; Start the server thread: ( define server-thread ( thread ( lambda ( ) ( serve null null ) ) ) ) ; — — — — — — — — — — — — — - ; Client-side helpers: ( define ( req-evt f ) ( nack-guard-evt ( lambda ( nack ) ; Be sure that the server thread is running: ( thread-resume server-thread ( current-thread ) ) ; Create a channel to hold the reply: ( let ( [ ch ( make-channel ) ] ) ( f ch nack ) ch ) ) ) ) ( define ( read-or-peek-evt s skip evt peek? ) ( req-evt ( lambda ( ch nack ) ( channel-put read-req-ch ( list* s skip ch nack evt peek? ) ) ) ) ) ; Make the port: ( make-input-port ' mod3-cycle ; Each handler for the port just sends ; a request to the server ( lambda ( s ) ( read-or-peek-evt s 0 #f #f ) ) ( lambda ( s skip evt ) ( read-or-peek-evt s skip evt #t ) ) ( lambda ( ) ; close ( sync ( req-evt ( lambda ( ch nack ) ( channel-put progress-req-ch ( list* ch nack ) ) ) ) ) ) ( lambda ( ) ; progress-evt ( sync ( req-evt ( lambda ( ch nack ) ( channel-put progress-req-ch ( list* ch nack ) ) ) ) ) ) ( lambda ( k progress-evt done-evt ) ; commit ( sync ( req-evt ( lambda ( ch nack ) ( channel-put commit-req-ch ( list* k progress-evt done-evt ch nack ) ) ) ) ) ) ) )> > ( define mod3-cycle ( make-mod3-cycle ) )
> > ( let ( [ result1 #f ] [ result2 #f ] ) ( let ( [ t1 ( thread ( lambda ( ) ( set! result1 ( read-string 5 mod3-cycle ) ) ) ) ] [ t2 ( thread ( lambda ( ) ( set! result2 ( read-string 5 mod3-cycle ) ) ) ) ] ) ( thread-wait t1 ) ( thread-wait t2 ) ( string-append result1 "," result2 ) ) )
> "11120,02020"
> > ( define s ( make-bytes 1 ) )
> > ( define progress-evt ( port-progress-evt mod3-cycle ) )
> > ( peek-bytes-avail! s 0 progress-evt mod3-cycle )
> 1
> > s
> #"1"
> > ( port-commit-peeked 1 progress-evt ( make-semaphore 1 ) mod3-cycle )
> #t
> > ( sync/timeout 0 progress-evt )
> #<progress-evt>
> > ( peek-bytes-avail! s 0 progress-evt mod3-cycle )
> 0
> > ( port-commit-peeked 1 progress-evt ( make-semaphore 1 ) mod3-cycle )
> #f
> > ( close-input-port mod3-cycle )
> ```

> ```
(make-output-port name
    evt
    write-out
    close
   [ write-out-special
    get-write-evt
    get-write-special-evt
    get-location
    count-lines!
    init-position
    buffer-mode)    →    output-port?

  name : any/c
  evt : evt?
   write-out   :   ( or/c
> ( bytes? exact-nonnegative-integer?
> exact-nonnegative-integer?
> boolean?
> boolean?
> .  →  .
> ( or/c exact-nonnegative-integer?
> #f
> evt? ) )
> output-port? )

  close : (  →   any)
   write-out-special   :   ( or/c ( any/c boolean? boolean?
> .  →  .
> ( or/c any/c
> #f
> evt? ) )
> output-port?
> #f )   =   #f

   get-write-evt   :   ( or/c
> ( bytes? exact-nonnegative-integer?
> exact-nonnegative-integer?
> .  →  .
> evt? )
> #f )   =   #f

   get-write-special-evt   :   ( or/c
> ( any/c .  →  . evt? )
> #f )   =   #f

   get-location   :   ( or/c
> (  →
> ( values ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f ) ) )
> #f )
      =   #f

  count-lines! : (  →   any) = void
   init-position   :   ( or/c exact-positive-integer?
> port?
> #f
> (  →  ( or/c exact-positive-integer? #f ) ) )
      =   1

   buffer-mode   :   ( or/c ( case  →
> ( ( or/c ' block ' line ' none ) .  →  . any )
> (  →  ( or/c ' block ' line ' none #f ) ) )
> #f )
      =   #f
```


# 13.1.6 String Ports
(inclusive)	→
(-> bytes → list (subbytes s start end))```
Returns a list whose elements are produced by calling r on in until it produces [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29).
Examples:
> ```racket
> > ( define ( read-number input-port ) ( define char ( read-char input-port ) ) ( if ( eof-object? char ) char ( string->number ( string char ) ) ) )
> > ( port->list read-number ( open-input-string "12345" ) )
> '(1 2 3 4 5)
> ```
> ```
(current-input-port)	→
(-> current-input-port)
```
(current-input-port)	→
(-> open-input-string "hello world")```

Reads all bytes from in and returns them as a [byte string](bytestrings.html#%28tech._byte._string%29). The input port is closed unless close? is #f.

Example:

> ```racket
> > ( port->bytes ( open-input-string "hello world" ) )
> #"hello world"
> ```

Changed in version 6.8.0.2 of package base: Added the #:close? argument.

> ```
(current-input-port)	→
(-> listof string?)
```
(current-input-port)	→
(-> open-input-string "line 1\nline 2\n line 3\nline 4")```
Like [port->lines](#%28def._%28%28lib._racket%2Fport..rkt%29._port-~3elines%29%29), but reading bytes and collecting them into lines like [read-bytes-line](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes-line%29%29). The input port is closed unless close? is #f.
Example:
> ```racket
> > ( port->bytes-lines ( open-input-string "line 1\nline 2\n line 3\nline 4" ) )
> '(#"line 1" #"line 2" #" line 3" #"line 4")
> ```
Changed in version 6.8.0.2 of package base: Added the #:close? argument.
> ```


# 13.1.6 String Ports
(current-output-port)	→
(-> current-output-port)
```
Uses display on each element of lst to out, adding separator after each element.

> ```
(call-with-output-string proc)   →   string?
  proc : (output-port? .  →  . any)```

Calls proc with an output port that accumulates all output into a string, and returns the string.

The port passed to proc is like the one created by [open-output-string](stringport.html#%28def._%28%28quote._~23~25kernel%29._open-output-string%29%29), except that it is wrapped via [dup-output-port](#%28def._%28%28lib._racket%2Fport..rkt%29._dup-output-port%29%29), so that proc cannot access the port’s content using [get-output-string](stringport.html#%28def._%28%28quote._~23~25kernel%29._get-output-string%29%29). If control jumps back into proc, the port continues to accumulate new data, and [call-with-output-string](#%28def._%28%28lib._racket%2Fport..rkt%29._call-with-output-string%29%29) returns both the old data and newly accumulated data.

> ```
(call-with-output-bytes proc)  →  bytes?
  proc : (output-port? .  →  . any)
```
Like call-with-output-string, but returns the accumulated result in a byte string instead of a string. Furthermore, the port’s content is emptied when call-with-output-bytes returns, so that if control jumps back into proc and returns a second time, only the newly accumulated bytes are returned.
> ```
(with-output-to-string proc)   →   string?
  proc : (  →   any)```
Equivalent to
> ```racket
> ( call-with-output-string
> ( lambda ( p ) ( parameterize ( [ current-output-port p ] )
> ( proc ) ) ) )
> ```


# 13.1.6 String Ports
> ```
(with-output-to-bytes proc)  →  bytes?
  proc : (  →   any)
```
(parameter)	→
(-> input-port? . → . any)```

Equivalent to (proc ([open-input-string](stringport.html#%28def._%28%28quote._~23~25kernel%29._open-input-string%29%29) str)).

> ```
(call-with-input-bytes bstr proc)  →  any
  bstr : bytes?
  proc : (input-port? .  →  . any)
```
Equivalent to (proc (open-input-bytes bstr)).
> ```
(with-input-from-string str proc)   →   any
  str : string?
  proc : (  →   any)```
Equivalent to
> ```racket
> ( parameterize ( [ current-input-port ( open-input-string str ) ] )
> ( proc ) )
> ```
> ```
(with-input-from-bytes bstr proc)  →  any
  bstr : bytes?
  proc : (  →   any)


# 13.1.6 String Ports
```
(parameter)	→
(-> map object-name in)```

Takes any number of input ports and returns an input port. Reading from the input port draws bytes (and special non-byte values) from the given input ports in order. If close-at-eof? is true, then each port is closed when an end-of-file is encountered from the port, or when the result input port is closed. Otherwise, data not read from the returned input port remains available for reading in its original input port.

The name argument determines the name as reported by [object-name](inspectors.html#%28def._%28%28quote._~23~25kernel%29._object-name%29%29) for the returned input port.

See also [merge-input](#%28def._%28%28lib._racket%2Fport..rkt%29._merge-input%29%29), which interleaves data from multiple input ports as it becomes available.

Changed in version 6.90.0.19 of package base: Added the name argument.

> ```
(make-input-port/read-to-peek name
    read-in
    fast-peek
    close
   [ get-location
    count-lines!
    init-position
    buffer-mode
    buffering?
    on-consumed)    →    input-port?

  name : any/c
   read-in   :   ( bytes?
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt? ) )

   fast-peek   :   ( or/c #f
> ( bytes? exact-nonnegative-integer?
> ( bytes? exact-nonnegative-integer?
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f ) )
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f ) ) )

  close : (  →   any)
   get-location   :   ( or/c
> (  →
> ( values
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f ) ) )
> #f )   =   #f

  count-lines! : (  →   any) = void
  init-position : exact-positive-integer? = 1
   buffer-mode   :   ( or/c ( case  →  ( ( or/c ' block ' none ) .  →  . any )
> (  →  ( or/c ' block ' none #f ) ) )
> #f )
      =   #f

  buffering? : any/c = #f
   on-consumed   :   ( or/c ( ( or/c exact-nonnegative-integer? eof-object?
> procedure? evt? )
> .  →  . any )
> #f )
      =   #f
```


# 13.1.6 String Ports
Similar to make-input-port, but if the given read-in returns an event, the event’s value must be 0. The resulting port’s peek operation is implemented automatically (in terms of read-in) in a way that can handle special non-byte values. The progress-event and commit operations are also implemented automatically. The resulting port is thread-safe, but not kill-safe (i.e., if a thread is terminated or suspended while using the port, the port may become damaged).
The read-in, close, get-location, count-lines!, init-position, and buffer-mode procedures are the same as for make-input-port.
The fast-peek argument can be either #f or a procedure of three arguments: a byte string to receive a peek, a skip count, and a procedure of two arguments. The fast-peek procedure can either implement the requested peek, or it can dispatch to its third argument to implement the peek. The fast-peek is not used when a peek request has an associated progress event.
The buffering? argument determines whether read-in can be called to read more characters than are immediately demanded by the user of the new port. If buffer-mode is not #f, then buffering? determines the initial buffer mode, and buffering? is enabled after a buffering change only if the new mode is 'block.
If on-consumed is not #f, it is called when data is read (or committed) from the port, as opposed to merely peeked. The argument to on-consumed is the result value of the port’s reading procedure, so it can be an integer or any result from read-in.
> ```


# 13.1.6 String Ports
(make-limited-input-port in
    limit
   [ close-orig?)    →    input-port?
  in : input-port?
  limit : exact-nonnegative-integer?
  close-orig? : any/c = #t```
Returns a port whose content is drawn from in, but where an end-of-file is reported after limit bytes (and non-byte special values) have been read. If close-orig? is true, then the original port is closed if the returned port is closed.
Bytes are consumed from in only when they are consumed from the returned port. In particular, peeking into the returned port peeks into the original port.
If in is used directly while the resulting port is also used, then the limit bytes provided by the port need not be contiguous parts of the original port’s stream.
> ```
(make-pipe-with-specials [limit
    in-name
    out-name)    →    input-port?   output-port?
  limit : exact-nonnegative-integer? = #f
  in-name : any/c = 'pipe
  out-name : any/c = 'pipe


# 13.1.6 String Ports
```
Returns two ports: an input port and an output port. The ports behave like those returned by make-pipe, except that the ports support non-byte values written with procedures such as write-special and read with procedures such as get-byte-or-special.

The limit argument determines the maximum capacity of the pipe in bytes, but this limit is disabled if special values are written to the pipe before limit is reached. The limit is re-enabled after the special value is read from the pipe.

The optional in-name and out-name arguments determine the names of the result ports.

> ```
(combine-output a-out b-out)   →   output-port?
  a-out : output-port?
  b-out : output-port?```

Accepts two output ports and returns a new output port combining the original ports. When written to, the combined port first writes as many bytes as possible to a-out, and then tries to write the same number of bytes to b-out. If that doesn’t succeed, what is left over is buffered and no further writes can go through until the ports are evened out. The port is ready (for the purposes of synchronization) when each port reports being ready. However, the first port may stop being ready while waiting on the second port to sync, so it cannot be guaranteed that both ports are ready at once. Closing the combined port is done after writing all remaining bytes to b-out.

Added in version 7.7.0.10 of package base.

> ```
(merge-input a-in b-in [buffer-limit) → input-port?
  a-in : input-port?
  b-in : input-port?
  buffer-limit : (or/c exact-nonnegative-integer? #f) = 4096
```


# 13.1.6 String Ports
Accepts two input ports and returns a new input port. The new port merges the data from two original ports, so data can be read from the new port whenever it is available from either of the two original ports. The data from the original ports are interleaved. When an end-of-file has been read from an original port, it no longer contributes characters to the new port. After an end-of-file has been read from both original ports, the new port returns end-of-file. Closing the merged port does not close the original ports.
The optional buffer-limit argument limits the number of bytes to be buffered from a-in and b-in, so that the merge process does not advance arbitrarily beyond the rate of consumption of the merged data. A #f value disables the limit. As for make-pipe-with-specials, buffer-limit does not apply when a special value is produced by one of the input ports before the limit is reached.
See also input-port-append, which concatenates input streams instead of interleaving them.
> ```
(open-output-nowhere [name special-ok?) → output-port?
  name : any/c = 'nowhere
  special-ok? : any/c = #t```
Creates and returns an output port that discards all output sent to it (without blocking). The name argument is used as the port’s name. If the special-ok? argument is true, then the resulting port supports [write-special](Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._write-special%29%29), otherwise it does not.
> ```
(open-input-nowhere [name) → input-port?
  name : any/c = 'nowhere


# 13.1.6 String Ports
```
Creates and returns an input port that always returns eof (without blocking). The name argument is used as the port’s name.

Added in version 8.15.0.2 of package base.

> ```
(peeking-input-port in
   [ name
    skip
    #:init-position init-position)

   →   input-port?
  in : input-port?
  name : any/c = (object-name in)
  skip : exact-nonnegative-integer? = 0
  init-position : exact-positive-integer? = 1```

Returns an input port whose content is determined by peeking into in. In other words, the resulting port contains an internal skip count, and each read of the port peeks into in with the internal skip count, and then increments the skip count according to the amount of data successfully peeked.

The optional name argument is the name of the resulting port. The skip argument is the port initial skip count, and it defaults to 0.

The resulting port’s initial position (as reported by [file-position](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-position%29%29)) is ([-](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._-%29%29) init-position 1), no matter the position of in.

The resulting port supports buffering, and a 'block buffer mode allows the port to peek further into in than requested. The resulting port’s initial buffer mode is 'block, unless in supports buffer mode and its mode is initially 'none (i.e., the initial buffer mode is taken from in when it supports buffering). If in supports buffering, adjusting the resulting port’s buffer mode via [file-stream-buffer-mode](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-stream-buffer-mode%29%29) adjusts in’s buffer mode.

For example, when you read from a peeking port, you see the same answers as when you read from the original port:

Examples:

> ```racket
> > ( define an-original-port ( open-input-string "123456789" ) )
> > ( define a-peeking-port ( peeking-input-port an-original-port ) )
> > ( file-stream-buffer-mode a-peeking-port ' none )
> > ( read-string 3 a-peeking-port )
> "123"
> > ( read-string 3 an-original-port )
> "123"
> ```

Beware that the read from the original port is invisible to the peeking port, which keeps its own separate internal counter, and thus interleaving reads on the two ports can produce confusing results. Continuing the example before, if we read three more characters from the peeking port, we end up skipping over the 456 in the port (but only because we disabled buffering above):

Example:

> ```racket
> > ( read-string 3 a-peeking-port )
> "789"
> ```

If we had left the buffer mode of a-peeking-port alone, that last [read-string](Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-string%29%29) would have likely produced "456" as a result of buffering bytes from an-original-port earlier.

Changed in version 6.1.0.3 of package base: Enabled buffering and buffer-mode adjustments via [file-stream-buffer-mode](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-stream-buffer-mode%29%29), and set the port’s initial buffer mode to that of in.

> ```
(reencode-input-port in
    encoding
   [ error-bytes
    close?
    name
    convert-newlines?
    enc-error)    →    input-port?

  in : input-port?
  encoding : string?
  error-bytes : (or/c #f bytes?) = #f
  close? : any/c = #f
  name : any/c = (object-name in)
  convert-newlines? : any/c = #f
   enc-error   :   (string? input-port? .  →  . any)
      =   (lambda (msg port) (error ...))
```


# 13.1.6 String Ports
Produces an input port that draws bytes from in, but converts the byte stream using (bytes-open-converter encoding-str "UTF-8"). In addition, if convert-newlines? is true, then decoded sequences that correspond to UTF-8 encodings of "\\r\\n", "\\r\\u0085", "\\r", "\\u0085", and "\\u2028" are all converted to the UTF-8 encoding of "\\n".
If error-bytes is provided and not #f, then the given byte sequence is used in place of bytes from in that trigger conversion errors. Otherwise, if a conversion is encountered, enc-error is called, which must raise an exception.
If close? is true, then closing the result input port also closes in. The name argument is used as the name of the result input port.
In non-buffered mode, the resulting input port attempts to draw bytes from in only as needed to satisfy requests. Toward that end, the input port assumes that at least n bytes must be read to satisfy a request for n bytes. (This is true even if the port has already drawn some bytes, as long as those bytes form an incomplete encoding sequence.)
> ```
(reencode-output-port out
    encoding
   [ error-bytes
    close?
    name
    newline-bytes
    enc-error)    →    output-port?
  out : output-port?
  encoding : string?
  error-bytes : (or/c #f bytes?) = #f
  close? : any/c = #f
  name : any/c = (object-name out)
  newline-bytes : (or/c #f bytes?) = #f
   enc-error   :   (string? output-port? .  →  . any)
      =   (lambda (msg port) (error ...))```


# 13.1.6 String Ports
Produces an output port that directs bytes to out, but converts its byte stream using ([bytes-open-converter](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes-open-converter%29%29) "UTF-8" encoding-str). In addition, if newline-bytes is not #f, then bytes written to the port that are the UTF-8 encoding of "\\n" are first converted to newline-bytes (before applying the convert from UTF-8 to encoding-str).
If error-bytes is provided and not #f, then the given byte sequence is used in place of bytes that have been sent to the output port and that trigger conversion errors. Otherwise, enc-error is called, which must raise an exception.
If close? is true, then closing the result output port also closes out. The name argument is used as the name of the result output port.
The resulting port supports buffering, and the initial buffer mode is ([or](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._or%29%29) ([file-stream-buffer-mode](port-buffers.html#%28def._%28%28quote._~23~25kernel%29._file-stream-buffer-mode%29%29) out) 'block). In 'block mode, the port’s buffer is flushed only when it is full or a flush is requested explicitly. In 'line mode, the buffer is flushed whenever a newline or carriage-return byte is written to the port. In 'none mode, the port’s buffer is flushed after every write. Implicit flushes for 'line or 'none leave bytes in the buffer when they are part of an incomplete encoding sequence.


# 13.1.6 String Ports
The resulting output port does not support atomic writes. An explicit flush or special-write to the output port can hang if the most recently written bytes form an incomplete encoding sequence.
When the port is buffered, a [flush callback](plumbers.html#%28tech._flush._callback%29) is registered with the [current plumber](plumbers.html#%28tech._current._plumber%29) to flush the buffer.
> ```
(dup-input-port in [close?) → input-port?
  in : input-port?
  close? : any/c = #f
```
Returns an input port that draws directly from in. Closing the resulting port closes in only if close? is #t.

The new port is initialized with the port read handler of in, but setting the handler on the result port does not affect reading directly from in.

> ```
(dup-output-port out [close?) → output-port?
  out : output-port?
  close? : any/c = #f```

Returns an output port that propagates data directly to out. Closing the resulting port closes out only if close? is #t.

The new port is initialized with the [port display handler](Writing.html#%28tech._port._display._handler%29) and [port write handler](Writing.html#%28tech._port._write._handler%29) of out, but setting the handlers on the result port does not affect writing directly to out.

> ```
(relocate-input-port in
    line
    column
    position
   [ close?]
    #:name name)    →    input-port?

  in : input-port?
  line : (or/c exact-positive-integer? #f)
  column : (or/c exact-nonnegative-integer? #f)
  position : exact-positive-integer?
  close? : any/c = #t
  name : (object-name in)
```


# 13.1.6 String Ports
Produces an input port that is equivalent to in except in how it reports location information (and possibly its name). The resulting port’s content starts with the remaining content of in, and it starts at the given line, column, and position. A #f for the line or column means that the line and column will always be reported as #f.
The line and column values are used only if line counting is enabled for in and for the resulting port, typically through port-count-lines!. The column value determines the column for the first line (i.e., the one numbered line), and later lines start at column 0. The given position is used even if line counting is not enabled.
When line counting is on for the resulting port, reading from in instead of the resulting port increments location reports from the resulting port. Otherwise, the resulting port’s position does not increment when data is read from in.
If close? is true, then closing the resulting port also closes in. If close? is #f, then closing the resulting port does not close in.
The name argument is used as the name for the resulting port; the default value keeps the same name as in.
> ```
(relocate-output-port out
    line
    column
    position
   [ close?]
    #:name name)    →    output-port?
  out : output-port?
  line : (or/c exact-positive-integer? #f)
  column : (or/c exact-nonnegative-integer? #f)
  position : exact-positive-integer?
  close? : any/c = #t
  name : (object-name out)```


# 13.1.6 String Ports
Like [relocate-input-port](#%28def._%28%28lib._racket%2Fport..rkt%29._relocate-input-port%29%29), but for output ports.
> ```
(transplant-input-port in
    get-location
    init-pos
   [ close?
    count-lines!]
    #:name name)    →    input-port?
  in : input-port?
   get-location   :   ( or/c
> (  →
> ( values
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f ) ) )
> #f )
  init-pos : exact-positive-integer?
  close? : any/c = #t
  count-lines! : (  →   any) = void
  name : (object-name in)


# 13.1.6 String Ports
```
Like relocate-input-port, except that arbitrary position information can be produced (when line counting is enabled) via get-location, which is used as for make-input-port. If get-location is #f, then the port counts lines in the usual way starting from init-pos, independent of locations reported by in.

If count-lines! is supplied, it is called when line counting is enabled for the resulting port. The default is void.

> ```
(transplant-output-port out
    get-location
    init-pos
   [ close?
    count-lines!]
    #:name name)    →    output-port?

  out : output-port?
   get-location   :   ( or/c
> (  →
> ( values
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f ) ) )
> #f )

  init-pos : exact-positive-integer?
  close? : any/c = #t
  count-lines! : (  →   any) = void
  name : (object-name out)```

Like [transplant-input-port](#%28def._%28%28lib._racket%2Fport..rkt%29._transplant-input-port%29%29), but for output ports.

> ```
(filter-read-input-port in
    read-wrap
    peek-wrap
   [ close?)    →    input-port?

  in : input-port?
   read-wrap   :   ( bytes? ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt? )
> .  →  .
> ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt? ) )

   peek-wrap   :   ( bytes? exact-nonnegative-integer? ( or/c evt? #f )
> ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f )
> .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f ) )

  close? : any/c = #t
```


# 13.1.6 String Ports
Creates a port that draws from in, but each result from the port’s read and peek procedures (in the sense of make-input-port) is filtered by read-wrap and peek-wrap. The filtering procedures each receive both the arguments and results of the read and peek procedures on in for each call.
If close? is true, then closing the resulting port also closes in.
> ```
(special-filter-input-port in proc [close?) → input-port?
  in : input-port?
   proc   :   ( procedure? bytes? .  →  . ( or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt? ) )
  close? : any/c = #t```
Produces an input port that is equivalent to in, except that when in produces a procedure to access a special value, proc is applied to the procedure to allow the special value to be replaced with an alternative. The proc is called with the special-value procedure and the byte string that was given to the port’s read or peek function (see [make-input-port](customport.html#%28def._%28%28quote._~23~25kernel%29._make-input-port%29%29)), and the result is used as the read or peek function’s result. The proc can modify the byte string to substitute a byte for the special value, but the byte string is guaranteed only to hold at least one byte.
If close? is true, then closing the resulting input port also closes in.


##### 13.1.10.3 Port Events
> ```
(eof-evt in)  →  evt?
  in : input-port?
```
Returns a synchronizable event that is ready when in produces an eof. If in produces a mid-stream eof, the eof is consumed by the event only if the event is chosen in a synchronization.

If attempting to read from in raises an exception during a synchronization attempt, then the exception may be reported during the synchronization attempt, but it will silently discarded if some another event in the same synchronization is selected or if some other event raises an exception first.

Changed in version 7.5.0.3 of package base: Changed handling of read errors so they are propagated to a synchronization attempt, instead of treated as unhandled errors in a background thread.

> ```
(read-bytes-evt k in)   →   evt?
  k : exact-nonnegative-integer?
  in : input-port?```

Returns a [synchronizable event](sync.html#%28tech._synchronizable._event%29) that is ready when k bytes can be read from in, or when an end-of-file is encountered in in. If k is 0, then the event is ready immediately with "". For non-zero k, if no bytes are available before an end-of-file, the event’s result is [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29). Otherwise, the event’s result is a byte string of up to k bytes, which contains as many bytes as are available (up to k) before an available end-of-file. (The result is a byte string of less than k bytes only when an end-of-file is encountered.)

Bytes are read from the port if and only if the event is chosen in a synchronization, and the returned bytes always represent contiguous bytes in the port’s stream.

The event can be synchronized multiple times—even concurrently—and each synchronization corresponds to a distinct read request.

The in must support progress events, and it must not produce a special non-byte value during the read attempt.

Exceptions attempting to read from in are handled in the same way as by [eof-evt](#%28def._%28%28lib._racket%2Fport..rkt%29._eof-evt%29%29).

> ```
(read-bytes!-evt bstr in)  →  evt?
  bstr : (and/c bytes? (not/c immutable?))
  in : input-port?
```


# 13.1.6 String Ports
Like read-bytes-evt, except that the read bytes are placed into bstr, and the number of bytes to read corresponds to (bytes-length bstr). The event’s result is either eof or the number of read bytes.
The bstr may be mutated any time after the first synchronization attempt on the event and until either the event is selected, a non-#f progress-evt is ready, or the current custodian (at the time of synchronization) is shut down. Note that there is no time bound otherwise on when bstr might be mutated if the event is not selected by a synchronzation; nevertheless, multiple synchronization attempts can use the same result from read-bytes!-evt as long as there is no intervening read on in until one of the synchronization attempts selects the event.
Exceptions attempting to read from in are handled in the same way as by eof-evt.
> ```
(read-bytes-avail!-evt bstr in)   →   evt?
  bstr : (and/c bytes? (not/c immutable?))
  in : input-port?```
Like [read-bytes!-evt](#%28def._%28%28lib._racket%2Fport..rkt%29._read-bytes%21-evt%29%29), except that the event reads only as many bytes as are immediately available, after at least one byte or one [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) becomes available.
> ```
(read-string-evt k in)  →  evt?
  k : exact-nonnegative-integer?
  in : input-port?


# 13.1.6 String Ports
```
Like read-bytes-evt, but for character strings instead of byte strings.

> ```
(read-string!-evt str in)   →   evt?
  str : (and/c string? (not/c immutable?))
  in : input-port?```

Like [read-bytes!-evt](#%28def._%28%28lib._racket%2Fport..rkt%29._read-bytes%21-evt%29%29), but for a character string instead of a byte string.

> ```
(read-line-evt in [mode) → evt?
  in : input-port?
   mode   :   (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
      =   'linefeed
```
Returns a synchronizable event that is ready when a line of characters or end-of-file can be read from in. The meaning of mode is the same as for read-line. The event result is the read line of characters (not including the line separator).
A line is read from the port if and only if the event is chosen in a synchronization, and the returned line always represents contiguous bytes in the port’s stream.
Exceptions attempting to read from in are handled in the same way as by eof-evt.
> ```
(read-bytes-line-evt in [mode) → evt?
  in : input-port?
   mode   :   (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
      =   'linefeed```
Like [read-line-evt](#%28def._%28%28lib._racket%2Fport..rkt%29._read-line-evt%29%29), but returns a byte string instead of a string.
> ```


# 13.1.6 String Ports
(peek-bytes-evt k skip progress-evt in)  →  evt?
  k : exact-nonnegative-integer?
  skip : exact-nonnegative-integer?
  progress-evt : (or/c progress-evt? #f)
  in : input-port?
(peek-bytes!-evt bstr skip progress-evt in)  →  evt?
  bstr : (and/c bytes? (not/c immutable?))
  skip : exact-nonnegative-integer?
  progress-evt : (or/c progress-evt? #f)
  in : input-port?
(peek-bytes-avail!-evt   bstr
    skip
    progress-evt
    in)    →    evt?
  bstr : (and/c bytes? (not/c immutable?))
  skip : exact-nonnegative-integer?
  progress-evt : (or/c progress-evt? #f)
  in : input-port?
(peek-string-evt k skip progress-evt in)  →  evt?
  k : exact-nonnegative-integer?
  skip : exact-nonnegative-integer?
  progress-evt : (or/c progress-evt? #f)
  in : input-port?
(peek-string!-evt str skip progress-evt in)  →  evt?
  str : (and/c string? (not/c immutable?))
  skip : exact-nonnegative-integer?
  progress-evt : (or/c progress-evt? #f)
  in : input-port?


# 13.1.6 String Ports
```
Like the read-bytes-evt, etc., functions, but for peeking. The skip argument indicates the number of bytes to skip, and progress-evt indicates an event that effectively cancels the peek (so that the event never becomes ready). The progress-evt argument can be #f, in which case the event is never canceled.

> ```
(regexp-match-evt pattern in)   →   any
  pattern : (or/c string? bytes? regexp? byte-regexp?)
  in : input-port?```

Returns a [synchronizable event](sync.html#%28tech._synchronizable._event%29) that is ready when pattern matches the stream of bytes/characters from in; see also [regexp-match](regexp.html#%28def._%28%28quote._~23~25kernel%29._regexp-match%29%29). The event’s value is the result of the match, in the same form as the result of [regexp-match](regexp.html#%28def._%28%28quote._~23~25kernel%29._regexp-match%29%29).

If pattern does not require a start-of-stream match, then bytes skipped to complete the match are read and discarded when the event is chosen in a synchronization.

Bytes are read from the port if and only if the event is chosen in a synchronization, and the returned match always represents contiguous bytes in the port’s stream. If not-yet-available bytes from the port might contribute to the match, the event is not ready. Similarly, if pattern begins with a start-of-stream ^ and the pattern does not initially match, then the event cannot become ready until bytes have been read from the port.

The event can be synchronized multiple times—even concurrently—and each synchronization corresponds to a distinct match request.

The in port must support progress events. If in returns a special non-byte value during the match attempt, it is treated like [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29).

Exceptions attempting to read from in are handled in the same way as by [eof-evt](#%28def._%28%28lib._racket%2Fport..rkt%29._eof-evt%29%29).

##### 13.1.10.4 Copying Streams

> ```
(parameter)	→
```


# 13.1.6 String Ports
(parameter)	→```
Reads data from in and writes it back out to out, returning when in produces [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29). The copy is efficient, and it is without significant buffer delays (i.e., a byte that becomes available on in is immediately transferred to out, even if future reads on in must block). If in produces a special non-byte value, it is transferred to out using [write-special](Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._write-special%29%29).
This function is often called from a “background” thread to continuously pump data from one stream to another.
If multiple outs are provided, data from in is written to every out. The different outs block output to each other, because each block of data read from in is written completely to one out before moving to the next out. The outs are written in the provided order, so non-blocking ports (e.g., file output ports) should be placed first in the argument list.
------------------------------------------------------------------------


# 13.2 Byte and String Input


### 13.2 Byte and String Input
> ```
(current-input-port)	→
(-> or/c char? eof-object?)
```
(current-input-port)	→
(-> or/c byte? eof-object?)```

Reads a single byte from in. If no bytes are available before an end-of-file, then [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) is returned.

Examples:

> ```racket
> > ( let ( [ ip ( open-input-string "a" ) ] ) ; The two values in the following list should be the same. ( list ( read-byte ip ) ( char->integer #\a ) ) )
> '(97 97)
> > ( let ( [ ip ( open-input-string ( string #\λ ) ) ] ) ; This string has a two byte-encoding. ( list ( read-byte ip ) ( read-byte ip ) ( read-byte ip ) ) )
> '(206 187 #<eof>)
> ```

> ```
(current-input-port)	→
(-> or/c string? eof-object?)
```
(s)	→
(-> or/c bytes? eof-object?)```
Like [read-line](#%28def._%28%28quote._~23~25kernel%29._read-line%29%29), but reads bytes and produces a byte string.
> ```
(current-input-port)	→
(-> or/c string? eof-object?)


# 13.2 Byte and String Input
```
(current-input-port)	→
(-> A temporary string of size amt is allocated while reading the input, even if the size of the result is less than amt characters.)```

> > > To read an entire port as bytes, use [port->bytes](port-lib.html#%28def._%28%28lib._racket%2Fport..rkt%29._port-~3ebytes%29%29).

Like [read-string](#%28def._%28%28quote._~23~25kernel%29._read-string%29%29), but reads bytes and produces a byte string.

Example:

> ```racket
> > ( let ( [ ip ( open-input-bytes ( bytes 6 115 101 99 114 101 116 ) ) ] ) ( define length ( read-byte ip ) ) ( bytes->string/utf-8 ( read-bytes length ip ) ) )
> "secret"
> ```

> ```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object?)
```
(inclusive)	→
(-> or/c exact-nonnegative-integer? eof-object?)```
Like [read-string!](#%28def._%28%28quote._~23~25kernel%29._read-string%21%29%29), but reads bytes, puts them into a byte string, and returns the number of bytes read.
Example:
> ```racket
> > ( let ( [ buffer ( make-bytes 10 ( char->integer #\_ ) ) ] [ ip ( open-input-string "cketRa" ) ] ) ( printf "~s\n" buffer ) ( read-bytes! buffer ip 2 6 ) ( printf "~s\n" buffer ) ( read-bytes! buffer ip 0 2 ) ( printf "~s\n" buffer ) )
> #"__________" #"__cket____" #"Racket____"
> ```
> ```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)


# 13.2 Byte and String Input
```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)```

Like [read-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._read-bytes-avail%21%29%29), but returns 0 immediately if no bytes (or specials) are available for reading and the end-of-file is not reached.

> ```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)
```
(current-input-port)	→
(-> or/c string? eof-object?)```
Similar to [read-string](#%28def._%28%28quote._~23~25kernel%29._read-string%29%29), except that the returned characters are [peek](ports.html#%28tech._peek%29)ed: preserved in the port for future reads and [peeks](ports.html#%28tech._peek%29). (More precisely, undecoded bytes are left for future reads and peeks.) The skip-bytes-amt argument indicates a number of bytes (not characters) in the input stream to skip before collecting characters to return; thus, in total, the next skip-bytes-amt bytes plus amt characters are inspected.
For most kinds of ports, inspecting skip-bytes-amt bytes and amt characters requires at least skip-bytes-amt+amt bytes of memory overhead associated with the port, at least until the bytes/characters are read. No such overhead is required when peeking into a string port (see [String Ports](stringport.html)), a pipe port (see [Pipes](pipeports.html)), or a custom port with a specific peek procedure (depending on how the peek procedure is implemented; see [Custom Ports](customport.html)).


# 13.2 Byte and String Input
If a port produces [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) mid-stream, attempts to skip beyond the [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) for a [peek](ports.html#%28tech._peek%29) always produce [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) until the [eof](port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29) is read.
> ```
(current-input-port)	→
(-> or/c bytes? eof-object?)
```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object?)```

Like [read-string!](#%28def._%28%28quote._~23~25kernel%29._read-string%21%29%29), but for [peek](ports.html#%28tech._peek%29)ing, and with a skip-bytes-amt argument like [peek-string](#%28def._%28%28quote._~23~25kernel%29._peek-string%29%29).

> ```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object?)
```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)```
Like [read-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._read-bytes-avail%21%29%29), but for [peek](ports.html#%28tech._peek%29)ing, and with two extra arguments. The skip-bytes-amt argument is as in [peek-bytes](#%28def._%28%28quote._~23~25kernel%29._peek-bytes%29%29). The progress argument must be either #f or an event produced by [port-progress-evt](#%28def._%28%28quote._~23~25kernel%29._port-progress-evt%29%29) for in.


# 13.2 Byte and String Input
To [peek](ports.html#%28tech._peek%29), [peek-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%29%29) blocks until finding an end-of-file, at least one byte (or special) past the skipped bytes, or until a non-#f progress becomes ready. Furthermore, if progress is ready before bytes are peeked, no bytes are peeked or skipped, and progress may cut short the skipping process if it becomes available during the peek attempt. Furthermore, progress is checked even before determining whether the port is still open.
The result of [peek-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%29%29) is 0 only
-   when start-pos is equal to end-pos, or
-   when progress becomes ready before bytes are peeked.
> ```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)
```
(current-input-port)	→
(-> or/c exact-nonnegative-integer? eof-object? procedure?)```

Like [read-bytes-avail!/enable-break](#%28def._%28%28quote._~23~25kernel%29._read-bytes-avail%21%2Fenable-break%29%29), but for [peek](ports.html#%28tech._peek%29)ing, and with skip-bytes-amt and progress arguments like [peek-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%29%29).

> ```
(current-input-port)	→
(-> or/c char? eof-object? any/c)
```
(current-input-port)	→
(-> or/c byte? eof-object? any/c)```
Like [read-char-or-special](#%28def._%28%28quote._~23~25kernel%29._read-char-or-special%29%29), but reads and returns a byte instead of a character.


# 13.2 Byte and String Input
Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.
> ```
(current-input-port)	→
(-> or/c char? eof-object?)
```
(current-input-port)	→
(-> or/c byte? eof-object?)```

Like [peek-char](#%28def._%28%28quote._~23~25kernel%29._peek-char%29%29), but [peeks](ports.html#%28tech._peek%29) and returns a byte instead of a character.

> ```
(current-input-port)	→
(-> or/c char? eof-object? any/c)
```
(current-input-port)	→
(-> or/c byte? eof-object? any/c)```
Like [peek-char-or-special](#%28def._%28%28quote._~23~25kernel%29._peek-char-or-special%29%29), but [peeks](ports.html#%28tech._peek%29) and returns a byte instead of a character, and it supports a progress argument like [peek-bytes-avail!](#%28def._%28%28quote._~23~25kernel%29._peek-bytes-avail%21%29%29).
Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.
Changed in version 6.90.0.16: Added 'special as an option for special-wrap.
> ```
(current-input-port)	→
(-> and/c input-port? port-provides-progress-evts?)


# 13.2 Byte and String Input
```
Returns a synchronizable event (see Events) that becomes ready for synchronization after any subsequent read from in or after in is closed. After the event becomes ready, it remains ready. The synchronization result of a progress event is the progress event itself.

> ```
(port-provides-progress-evts? in)   →   boolean
  in : input-port?```

Returns #t if [port-progress-evt](#%28def._%28%28quote._~23~25kernel%29._port-progress-evt%29%29) can return an event for in. All built-in kinds of ports support progress events, but ports created with [make-input-port](customport.html#%28def._%28%28quote._~23~25kernel%29._make-input-port%29%29) (see [Custom Ports](customport.html)) may not.

> ```
(current-input-port)	→
(-> current-input-port)
```
(current-input-port)	→
(-> current-input-port)```
Returns #t if ([read-byte](#%28def._%28%28quote._~23~25kernel%29._read-byte%29%29) in) would not block (at the time that [byte-ready?](#%28def._%28%28quote._~23~25kernel%29._byte-ready~3f%29%29) was called, at least). Equivalent to ([and](if.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._and%29%29) ([sync/timeout](sync.html#%28def._%28%28quote._~23~25kernel%29._sync%2Ftimeout%29%29) 0 in) #t).


# 13.2 Byte and String Input
The [byte-ready?](#%28def._%28%28quote._~23~25kernel%29._byte-ready~3f%29%29) and [char-ready?](#%28def._%28%28quote._~23~25kernel%29._char-ready~3f%29%29) functions are appropriate for relatively few applications, because ports are meant to support streaming data among concurrent producers and consumers; the fact that a byte or character is not ready in some instant does not necessarily mean that the producer is finished supplying data. (Also, if a port has multiple consumers, data might get consumed between the time that a given process uses [byte-ready?](#%28def._%28%28quote._~23~25kernel%29._byte-ready~3f%29%29) to poll the port and the time that it reads data from the port.) Using [byte-ready?](#%28def._%28%28quote._~23~25kernel%29._byte-ready~3f%29%29) makes sense if you are implementing your own scheduler or if you know that the port’s implementation and use are particularly constrained.
> ```
(current-input-port)	→
(-> current-input-port)


# 13.2 Byte and String Input
```
Returns #t if (read-char in) would not block (at the time that char-ready? was called, at least). Depending on the initial bytes of the stream, multiple bytes may be needed to form a UTF-8 encoding.

See byte-ready? for a note on how byte-ready? and char-ready? are rarely the right choice.

> ```
(progress-evt? v)   →   boolean?
  v : any/c
(progress-evt? evt in)   →   boolean?
  evt : progress-evt?
  in : input-port?```

With one argument, returns #t is v is a progress evt for some input port, #f otherwise.

With two arguments, returns #t if evt is a progress event for in, #f otherwise.

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

# 13.3 Byte and String Output

### 13.3 Byte and String Output

> ```
(current-output-port)	→
(-> current-output-port)
```
(current-output-port)	→
(-> current-output-port)```
Writes a single byte to out.
> ```
(current-output-port)	→
(-> current-output-port)


# 13.2 Byte and String Input
```
(current-output-port)	→
(-> current-output-port)```

Writes characters to out from str starting from index start-pos (inclusive) up to end-pos (exclusive). Like [substring](strings.html#%28def._%28%28quote._~23~25kernel%29._substring%29%29), the [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised if start-pos or end-pos is out-of-range for str.

The result is the number of characters written to out, which is always ([-](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._-%29%29) end-pos start-pos).

If str is mutable, mutations after [write-string](#%28def._%28%28quote._~23~25kernel%29._write-string%29%29) returns do not affect the characters written to out. (This independence from mutation is not a special property of [write-string](#%28def._%28%28quote._~23~25kernel%29._write-string%29%29), but instead generally true of output functions.)

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


# 13.2 Byte and String Input
Like [write-bytes](#%28def._%28%28quote._~23~25kernel%29._write-bytes%29%29), but returns without blocking after writing as many bytes as it can immediately flush. It blocks only if no bytes can be flushed immediately. The result is the number of bytes written and flushed to out; if start-pos is the same as end-pos, then the result can be 0 (indicating a successful flush of any buffered data), otherwise the result is between 1 and ([-](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._-%29%29) end-pos start-pos), inclusive.
The [write-bytes-avail](#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%29%29) procedure never drops bytes; if [write-bytes-avail](#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%29%29) successfully writes some bytes and then encounters an error, it suppresses the error and returns the number of written bytes. (The error will be triggered by future writes.) If an error is encountered before any bytes have been written, an exception is raised.
> ```
(current-output-port)	→
(-> or/c exact-nonnegative-integer? #f)


# 13.2 Byte and String Input
```
(current-output-port)	→
(-> current-output-port)```

Like [write-bytes-avail](#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%29%29), except that breaks are enabled during the write. The procedure provides a guarantee about the interaction of writing and breaks: if breaking is disabled when [write-bytes-avail/enable-break](#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%2Fenable-break%29%29) is called, and if the [exn:break](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) exception is raised as a result of the call, then no bytes will have been written to out. See also [Breaks](breakhandler.html).

> ```
(current-output-port)	→
(-> current-output-port)
```
(current-output-port)	→
(-> current-output-port)```
Like [write-special](#%28def._%28%28quote._~23~25kernel%29._write-special%29%29), but without blocking. If v cannot be written immediately, the result is #f without writing v, otherwise the result is #t and v is written.
> ```
(current-output-port)	→
(-> current-output-port)


# 13.2 Byte and String Input
```
(unbuffered)	→
(-> current-output-port)```

Similar to [write-special](#%28def._%28%28quote._~23~25kernel%29._write-special%29%29), but instead of writing the special value immediately, it returns a synchronizable event (see [Events](sync.html)). The out must support atomic writes, as indicated by [port-writes-atomic?](#%28def._%28%28quote._~23~25kernel%29._port-writes-atomic~3f%29%29).

Synchronizing on the object starts a write of the special value, and the event becomes ready when the value is written (unbuffered) to the port. If the event is not selected in a synchronization, then no value will have been written to out.

> ```
(port-writes-atomic? out)  →  boolean?
  out : output-port?
```
Returns #t if write-bytes-avail/enable-break can provide an exclusive-or guarantee (break or write, but not both) for out, and if the port can be used with procedures like write-bytes-avail-evt. Racket’s file-stream ports, pipes, string ports, and TCP ports all support atomic writes; ports created with make-output-port (see Custom Ports) may support atomic writes.
> ```
(port-writes-special? out)   →   boolean?
  out : output-port?```
Returns #t if procedures like [write-special](#%28def._%28%28quote._~23~25kernel%29._write-special%29%29) can write arbitrary values to the port. Racket’s file-stream ports, pipes, string ports, and TCP ports all reject special values, but ports created with [make-output-port](customport.html#%28def._%28%28quote._~23~25kernel%29._make-output-port%29%29) (see [Custom Ports](customport.html)) may support them.


# 13.2 Byte and String Input
------------------------------------------------------------------------


# 13.4 Reading


### 13.4 Reading
> ```
(current-input-port)	→
(-> current-input-port)
```
(current-input-port)	→
(-> or/c syntax? eof-object?)```

Like [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29), but produces a [syntax object](syntax-model.html#%28tech._syntax._object%29) with source-location information. The source-name is used as the source field of the syntax object; it can be an arbitrary value, but it should generally be a path for the source file.

See [The Reader](reader.html) for information on the default reader in [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) mode and [Reading via an Extension](reader.html#%28part._parse-reader%29) for the protocol of [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29).

Typically, line counting should be enabled for in so that source locations in syntax objects are in characters, instead of bytes. See also [Counting Positions, Lines, and Columns](linecol.html).

> > > <img src="finger.png" width="24" height="24" alt="+" />See also [Syntax Objects](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=stx-obj.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).

> ```
(current-input-port)	→
(-> current-input-port)
```
(current-input-port)	→
(-> object-name in)```


# 13.4 Reading
Analogous to calling [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29), but the resulting value encapsulates S-expression structure with source-location information. As with [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29), when [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29) is used within the dynamic extent of [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29), the result from [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29) is either a special-comment value, end-of-file, or opaque graph-structure placeholder (not a syntax object). The placeholder can be embedded in an S-expression or syntax object returned by a reader macro, etc., and it will be replaced with the actual syntax object before the outermost [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) returns.


# 13.4 Reading
Using [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29) within the dynamic extent of [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) does not allow graph structure for reading to be included in the outer [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) parsing, and neither does using [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29) within the dynamic extent of [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29). In those cases, [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29) and [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29) produce results like [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29) and [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29), except that a special-comment value is returned when the input stream starts with a comment (after whitespace).
See [Readtables](readtables.html) for an extended example that uses [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29).
Changed in version 6.2 of package base: Adjusted use of readtable in the same way as for [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29).
> ```
(current-input-port)	→
(-> or/c (any/c any/c . → . any) #f)


# 13.4 Reading
```
(read-case-sensitive)	→
(-> read-case-sensitive on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls parsing and printing of symbols. When this parameter’s value is #f, the reader case-folds symbols (e.g., producing 'hi when the input is any one of hi, Hi, HI, or hI). The parameter also affects the way that [write](Writing.html#%28def._%28%28quote._~23~25kernel%29._write%29%29) prints symbols containing uppercase characters; if the parameter’s value is #f, then symbols are printed with uppercase characters quoted by a \\ or \|. The parameter’s value is overridden by quoting \\ or \| vertical-bar quotes and the #cs and #ci prefixes; see [Reading Symbols](reader.html#%28part._parse-symbol%29) for more information. While a module is loaded, the parameter is set to #t (see [current-load](eval.html#%28def._%28%28quote._~23~25kernel%29._current-load%29%29)).

> ```
(read-square-bracket-as-paren)	→
(-> read-square-bracket-as-paren on?)
```
(read-curly-brace-as-paren)	→
(-> read-curly-brace-as-paren on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls whether { and } are treated as parentheses. See [Reading Pairs and Lists](reader.html#%28part._parse-pair%29) for more information.
> ```
(read-square-bracket-with-tag)	→
(-> read-square-bracket-with-tag on?)


# 13.4 Reading
```
(read-curly-brace-with-tag)	→
(-> read-curly-brace-with-tag on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls whether { and } are treated as parentheses, but the resulting list tagged with #%braces. See [Reading Pairs and Lists](reader.html#%28part._parse-pair%29) for more information.

Added in version 6.3.0.5 of package base.

> ```
(read-accept-box)	→
(-> read-accept-box on?)
```
(read-accept-compiled)	→
(-> read-accept-compiled on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls parsing #\~ compiled input. See [The Reader](reader.html) and [current-compile](eval.html#%28def._%28%28quote._~23~25kernel%29._current-compile%29%29) for more information.
> ```
(read-accept-bar-quote)	→
(-> read-accept-bar-quote on?)
```
(read-accept-graph)	→
(-> read-accept-graph on?)```

A parameter value that controls parsing input with sharing in [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29) mode. See [Reading Graph Structure](reader.html#%28part._parse-graph%29) for more information.

> ```
(read-syntax-accept-graph)	→
(-> read-syntax-accept-graph on?)
```
(read-decimal-as-inexact)	→
(-> read-decimal-as-inexact on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls parsing input numbers with a decimal point or exponent (but no explicit exactness tag). See [Reading Numbers](reader.html#%28part._parse-number%29) for more information.
> ```
(read-single-flonum)	→
(-> read-single-flonum on?)


# 13.4 Reading
```
(read-accept-dot)	→
(-> read-accept-dot on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls parsing input with a dot, which is normally used for literal cons cells. See [Reading Pairs and Lists](reader.html#%28part._parse-pair%29) for more information.

> ```
(read-accept-infix-dot)	→
(-> read-accept-infix-dot on?)
```
(read-cdot)	→
(-> read-cdot on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls parsing input with a dot, in a C structure accessor style. See [Reading with C-style Infix-Dot Notation](reader.html#%28part._parse-cdot%29) for more information.
Added in version 6.3.0.5 of package base.
> ```
(read-accept-quasiquote)	→
(-> read-accept-quasiquote on?)
```
(read-accept-reader)	→
(-> read-accept-reader on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls whether #reader, #lang, or #! are allowed for selecting a parser. See [Reading via an Extension](reader.html#%28part._parse-reader%29) for more information.

> ```
(read-accept-lang)	→
(-> read-accept-lang on?)
```
(current-readtable)	→
(-> or/c readtable? #f)
(current-readtable readtable) → void?
    readtable	:
(-> or/c readtable? #f)```
A parameter whose value determines a readtable that adjusts the parsing of S-expression input, where #f implies the default behavior. See [Readtables](readtables.html) for more information.
> ```
(parameter)	→
(-> any)


# 13.4 Reading
```
(current-reader-guard)	→
(-> any/c . → . any)
(current-reader-guard proc) → void?
    proc	:
(-> any/c . → . any)```

A parameter whose value converts or rejects (by raising an exception) a module-path datum following #reader. See [Reading via an Extension](reader.html#%28part._parse-reader%29) for more information.

> ```
(read-on-demand-source)	→
(-> or/c #f #t (and/c path? complete-path?))
(read-on-demand-source mode) → void?
    mode	:
(-> or/c #f #t (and/c path? complete-path?))
```
(parameter)	→
(-> case →
    (input-port? . → . any)
    (input-port? any/c . → . any))```
Gets or sets the port read handler for in. The handler called to read from the port when the built-in [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29) or [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29) procedure is applied to the port. (The port read handler is not used for [read/recursive](#%28def._%28%28quote._~23~25kernel%29._read%2Frecursive%29%29) or [read-syntax/recursive](#%28def._%28%28quote._~23~25kernel%29._read-syntax%2Frecursive%29%29).)
A port read handler is applied to either one argument or two arguments:
-   A single argument is supplied when the port is used with [read](#%28def._%28%28quote._~23~25kernel%29._read%29%29); the argument is the port being read. The return value is the value that was read from the port (or end-of-file).


# 13.4 Reading
-   Two arguments are supplied when the port is used with [read-syntax](#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29); the first argument is the port being read, and the second argument is a value indicating the source. The return value is a syntax object that was read from the port (or end-of-file).
The default port read handler reads standard Racket expressions with Racket’s built-in parser (see [The Reader](reader.html)). It handles a special result from a custom input port (see [make-input-port](customport.html#%28def._%28%28quote._~23~25kernel%29._make-input-port%29%29)) by treating it as a single expression, except that special-comment values (see [Special Comments](special-comments.html)) are treated as whitespace.
The default port read handler itself can be customized through a readtable; see [Readtables](readtables.html) for more information.
------------------------------------------------------------------------


# 13.5 Writing


### 13.5 Writing
> ```
(current-output-port)	→
(-> current-output-port)
```
(current-output-port)	→
(-> current-output-port)```

Displays datum to out, similar to [write](#%28def._%28%28quote._~23~25kernel%29._write%29%29), but usually in such a way that byte- and character-based datatypes are written as raw bytes or characters. If out has a handler associated to it via [port-display-handler](#%28def._%28%28quote._~23~25kernel%29._port-display-handler%29%29), then the handler is called. Otherwise, the [default printer](printing.html) is used (in [display](#%28def._%28%28quote._~23~25kernel%29._display%29%29) mode), as configured by various parameters.

See [The Printer](printing.html) for more information about the default printer. In particular, note that [display](#%28def._%28%28quote._~23~25kernel%29._display%29%29) may require memory proportional to the depth of the value being printed, due to the initial cycle check.

> ```
(current-output-port)	→
(-> current-output-port)
```
(current-output-port)	→
(-> current-output-port)```
The same as ([write](#%28def._%28%28quote._~23~25kernel%29._write%29%29) datum out) followed by ([newline](Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._newline%29%29) out).
Added in version 6.1.1.8 of package base.
> ```
(current-output-port)	→
(-> current-output-port)


# 13.5 Writing
```
(current-output-port)	→
(-> current-output-port)```

The same as ([print](#%28def._%28%28quote._~23~25kernel%29._print%29%29) datum out quote-depth) followed by ([newline](Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._newline%29%29) out).

The [println](#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._println%29%29) function is not equivalent to println in other languages, because [println](#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._println%29%29) uses printing conventions that are closer to [write](#%28def._%28%28quote._~23~25kernel%29._write%29%29) than to [display](#%28def._%28%28quote._~23~25kernel%29._display%29%29). For a closer analog to println in other languages, use [displayln](#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._displayln%29%29).

Added in version 6.1.1.8 of package base.

> ```
(parameter)	→
```
(error-print-width)	→
(-> see char-whitespace?)```
The same as ([fprintf](#%28def._%28%28quote._~23~25kernel%29._fprintf%29%29) ([current-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29)) form v [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)).
> ```
(parameter)	→


# 13.5 Writing
```
(current-error-port)	→```

Formats to a string. The result is the same as

> ```racket
> ( let ( [ o ( open-output-string ) ] )
> ( fprintf o form v ... )
> ( get-output-string o ) )
> ```

Example:

> ```racket
> > ( format "~a as a string is ~s.\n" ' ( 3 4 ) "(3 4)" )
> "(3 4) as a string is \"(3 4)\".\n"
> ```

> ```
(print-pair-curly-braces)	→
(-> print-pair-curly-braces on?)
```
(print-mpair-curly-braces)	→
(-> print-mpair-curly-braces on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls pair printing. If the value is true, then mutable pairs print using { and } instead of ( and ). The default is #t.
> ```
(print-unreadable)	→
(-> print-unreadable on?)
```
(print-graph)	→
(-> print-graph on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls printing data with sharing; defaults to #f. See [The Printer](printing.html) for more information.

> ```
(print-struct)	→
(-> print-struct on?)
```
(print-box)	→
(-> print-box on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls printing box values; defaults to #t. See [Printing Boxes](printing.html#%28part._print-box%29) for more information.
> ```
(print-vector-length)	→
(-> print-vector-length on?)
```
(print-hash-table)	→
(-> print-hash-table on?)```

A [parameter](eval-model.html#%28tech._parameter%29) that controls printing hash tables; defaults to #t. See [Printing Hash Tables](printing.html#%28part._print-hashtable%29) for more information.

> ```
(print-boolean-long-form)	→
(-> print-boolean-long-form on?)
```


# 13.5 Writing
(print-reader-abbreviations)	→
(-> print-reader-abbreviations on?)```
A [parameter](eval-model.html#%28tech._parameter%29) that controls printing of two-element lists that start with [quote](quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29), 'quasiquote, 'unquote, 'unquote-splicing, 'syntax, 'quasisyntax, 'unsyntax, or 'unsyntax-splicing; defaults to #f. See [Printing Pairs and Lists](printing.html#%28part._print-pairs%29) for more information.
> ```
(print-as-expression)	→
(-> print-as-expression on?)
```
(print-syntax-width)	→
(-> or/c +inf.0 0 (and/c exact-integer? (>/c 3)))
(print-syntax-width width) → void?
    width	:
(-> or/c +inf.0 0 (and/c exact-integer? (>/c 3)))```

A [parameter](eval-model.html#%28tech._parameter%29) that controls printing of [syntax objects](syntax-model.html#%28tech._syntax._object%29). Up to width characters are used to show the datum form of a syntax object within #\<syntax...> (after the [syntax object](syntax-model.html#%28tech._syntax._object%29)’s source location, if any), where ... is used as the last three characters if the printed form would otherwise be longer than width characters. A value of 0 for width means that the datum is not shown at all.

> ```
(print-value-columns)	→
(-> or/c +inf.0 (and/c exact-integer? (>/c 5)))
(print-value-columns columns) → void?
    columns	:
(-> or/c +inf.0 (and/c exact-integer? (>/c 5)))
```


# 13.5 Writing
(current-write-relative-directory)	→
(-> or/c (and/c path? complete-path?)
    (cons/c (and/c path? complete-path?)
    (and/c path? complete-path?))
    #f)
(current-write-relative-directory path) → void?
    path	:
(-> or/c (and/c path? complete-path?)
    (cons/c (and/c path? complete-path?)
    (and/c path? complete-path?))
    #f)```
A [parameter](eval-model.html#%28tech._parameter%29) that is used when writing compiled code (see [Printing Compiled Code](printing.html#%28part._print-compiled%29)) that contains pathname literals, including source-location pathnames for procedure names. When the parameter’s value is a path, paths that syntactically extend path are converted to relative paths; when the resulting compiled code is read, relative paths are converted back to complete paths using the [current-load-relative-directory](eval.html#%28def._%28%28quote._~23~25kernel%29._current-load-relative-directory%29%29) parameter (if it is not #f; otherwise, the path is left relative). When the parameter’s value is ([cons](pairs.html#%28def._%28%28quote._~23~25kernel%29._cons%29%29) rel-to-path base-path), then paths that syntactically extend base-path are converted as relative to rel-to-path; the rel-to-path must extend base-path, in which case 'up path elements (in the sense of [build-path](Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29)) may be used to make a path relative to rel-to-path.
> ```
(parameter)	→
(-> any/c output-port? . → . any)


# 13.5 Writing
```
(respectively)	→
(-> * (any/c output-port?) ((or/c 0 1)) any)```

A [parameter](eval-model.html#%28tech._parameter%29) that determines global port print handler, which is called by the default port print handler (see [port-print-handler](#%28def._%28%28quote._~23~25kernel%29._port-print-handler%29%29)) to [print](#%28def._%28%28quote._~23~25kernel%29._print%29%29) values into a port. The default value is equivalent to [default-global-port-print-handler](#%28def._%28%28quote._~23~25kernel%29._default-global-port-print-handler%29%29).

A [global port print handler](#%28tech._global._port._print._handler%29) optionally accepts a third argument, which corresponds to the optional third argument to [print](#%28def._%28%28quote._~23~25kernel%29._print%29%29). If a procedure given to [global-port-print-handler](#%28def._%28%28quote._~23~25kernel%29._global-port-print-handler%29%29) does not accept a third argument, it is wrapped with a procedure that discards the optional third argument.

> ```
(parameter)	→
(-> or/c 0 1)
```
(current-output-port)	→
(-> current-output-port)```


# 13.5 Writing
Pretty-prints the value v using the same printed form as the default [print](Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29) mode, but with newlines and whitespace inserted to avoid lines longer than ([pretty-print-columns](#%28def._%28%28lib._racket%2Fpretty..rkt%29._pretty-print-columns%29%29)), as controlled by ([pretty-print-current-style-table](#%28def._%28%28lib._racket%2Fpretty..rkt%29._pretty-print-current-style-table%29%29)). The printed form ends in a newline by default, unless the newline? argument is supplied with false or the [pretty-print-columns](#%28def._%28%28lib._racket%2Fpretty..rkt%29._pretty-print-columns%29%29) parameter is set to 'infinity. When port has line counting enabled (see [Counting Positions, Lines, and Columns](linecol.html)), then printing is sensitive to the column when printing starts—both for determining an initial line break and indenting subsequent lines.