40 lines
20 KiB
HTML
40 lines
20 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>13.1 Ports</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewlink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewselflink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewlink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</a></td></tr><tr><td align="right">18 </td><td><a href="running.html" class="tocviewlink
|
||
|
|
produces bytes, while an <a name="(tech._output._port)"></a><span style="font-style: italic">output port</span> consumes bytes (and
|
||
|
|
some ports are both input ports and output ports). When an input port
|
||
|
|
is provided to a character-based operation, the bytes are decoded to a
|
||
|
|
character, and character-based output operations similarly encode the
|
||
|
|
character to bytes; see <a href="encodings.html" data-pltdoc="x">Encodings and Locales</a>. In addition to bytes and
|
||
|
|
characters encoded as bytes, some ports can produce and/or consume
|
||
|
|
arbitrary values as <a name="(tech._special)"></a><span style="font-style: italic">special</span> results.</p><p>When a port corresponds to a file, network connection, or some other
|
||
|
|
system resource, it must be explicitly closed via
|
||
|
|
<span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-input-port%29%29" class="RktValLink" data-pltdoc="x">close-input-port</a></span> or <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._close-output-port%29%29" class="RktValLink" data-pltdoc="x">close-output-port</a></span> (or indirectly
|
||
|
|
via <span class="RktSym"><a href="custodians.html#%28def._%28%28quote._~23~25kernel%29._custodian-shutdown-all%29%29" class="RktValLink" data-pltdoc="x">custodian-shutdown-all</a></span>) to release low-level resources
|
||
|
|
associated with the port. For any kind of port, after it is closed,
|
||
|
|
attempting to read from or write to the port raises <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29" class="RktValLink" data-pltdoc="x">exn:fail</a></span>.</p><p>Data produced by a <a href="ports.html#%28tech._input._port%29" class="techoutside" data-pltdoc="x"><span class="techinside">input port</span></a> can be read or <a name="(tech._peek)"></a><span style="font-style: italic">peeked</span>. When data is read, it is considered consumed and
|
||
|
|
removed from the port’s stream. When data is <a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a>ed, it remains
|
||
|
|
in the port’s stream to be returned again by the next read or
|
||
|
|
<a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a>. Previously peeked data can be <a name="(tech._commit)"></a><span style="font-style: italic">committed</span>, which causes the data to be removed from the
|
||
|
|
port as for a read in a way that can be synchronized with other
|
||
|
|
attempts to <a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a> or read through a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable
|
||
|
|
event</span></a>. Both read and <a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a> operations are normally blocking, in
|
||
|
|
the sense that the read or <a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a> operation does not complete
|
||
|
|
until data is available from the port; non-blocking variants of read
|
||
|
|
and <a href="ports.html#%28tech._peek%29" class="techoutside" data-pltdoc="x"><span class="techinside">peek</span></a> operations are also available.</p><p>The global variable <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29" class="RktValLink" data-pltdoc="x">eof</a></span> is bound to the end-of-file value,
|
||
|
|
and <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof-object~3f%29%29" class="RktValLink" data-pltdoc="x">eof-object?</a></span> returns <span class="RktVal">#t</span> only when applied to this
|
||
|
|
value. Reading from a port produces an end-of-file result when the
|
||
|
|
port has no more data, but some ports may also return end-of-file
|
||
|
|
mid-stream. For example, a port connected to a Unix terminal returns
|
||
|
|
an end-of-file when the user types control-D; if the user provides
|
||
|
|
more input, the port returns additional bytes after the end-of-file.</p><p>Every port has a name, as reported by <span class="RktSym"><a href="inspectors.html#%28def._%28%28quote._~23~25kernel%29._object-name%29%29" class="RktValLink" data-pltdoc="x">object-name</a></span>. The name
|
||
|
|
can be any value, and it is used mostly for error-reporting
|
||
|
|
purposes. The <span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29" class="RktValLink" data-pltdoc="x">read-syntax</a></span> procedure uses the name of an input
|
||
|
|
port as the default source location for the <a href="syntax-model.html#%28tech._syntax._object%29" class="techoutside" data-pltdoc="x"><span class="techinside">syntax objects</span></a> that
|
||
|
|
it produces.</p><p>A port can be used as a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a>. An input port is
|
||
|
|
<a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> when <span class="RktSym"><a href="Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-byte%29%29" class="RktValLink" data-pltdoc="x">read-byte</a></span> would not
|
||
|
|
block, and an output port is <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> when
|
||
|
|
<span class="RktSym"><a href="Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%29%29" class="RktValLink" data-pltdoc="x">write-bytes-avail</a></span> would not block or when the port contains
|
||
|
|
buffered characters and <span class="RktSym"><a href="Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%2A%29%29" class="RktValLink" data-pltdoc="x">write-bytes-avail*</a></span> can flush part of
|
||
|
|
the buffer (although <span class="RktSym"><a href="Byte_and_String_Output.html#%28def._%28%28quote._~23~25kernel%29._write-bytes-avail%29%29" class="RktValLink" data-pltdoc="x">write-bytes-avail</a></span> might block). A value
|
||
|
|
that can act as both an input port and an output port acts as an input
|
||
|
|
port for a <a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a>. The <a href="sync.html#%28tech._synchronization._result%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronization result</span></a> of a port is the port itself.</p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><a href="encodings.html" class="toclink" data-pltdoc="x">13.1.1<span class="hspace"> </span>Encodings and Locales</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-ops.html" class="toclink" data-pltdoc="x">13.1.2<span class="hspace"> </span>Managing Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-buffers.html" class="toclink" data-pltdoc="x">13.1.3<span class="hspace"> </span>Port Buffers and Positions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="linecol.html" class="toclink" data-pltdoc="x">13.1.4<span class="hspace"> </span>Counting Positions, Lines, and Columns</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="file-ports.html" class="toclink" data-pltdoc="x">13.1.5<span class="hspace"> </span>File Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="stringport.html" class="toclink" data-pltdoc="x">13.1.6<span class="hspace"> </span>String Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pipeports.html" class="toclink" data-pltdoc="x">13.1.7<span class="hspace"> </span>Pipes</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="portstructs.html" class="toclink" data-pltdoc="x">13.1.8<span class="hspace"> </span>Structures as Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="customport.html" class="toclink" data-pltdoc="x">13.1.9<span class="hspace"> </span>Custom Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-lib.html" class="toclink" data-pltdoc="x">13.1.10<span class="hspace"> </span>More Port Constructors, Procedures, and Events</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-lib.html#%28part._.Port_.String_and_.List_.Conversions%29" class="toclink" data-pltdoc="x">13.1.10.1<span class="hspace"> </span>Port String and List Conversions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-lib.html#%28part._.Creating_.Ports%29" class="toclink" data-pltdoc="x">13.1.10.2<span class="hspace"> </span>Creating Ports</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-lib.html#%28part._.Port_.Events%29" class="toclink" data-pltdoc="x">13.1.10.3<span class="hspace"> </span>Port Events</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="port-lib.html#%28part._.Copying_.Streams%29" class="toclink" data-pltdoc="x">13.1.10.4<span class="hspace"> </span>Copying Streams</a></p></td></tr></table><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" id="searchbox" type="text" tabindex="1" placeholder="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "8.6", "../");"/></form> <a href="https://docs.racket-lang.org/index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("8.6");">top</a><span class="tocsettoggle"> <a href="javascript:void(0);" title="show/hide table of contents" onclick="TocsetToggle();">contents</a></span></span><span class="navright"> <a href="input-and-output.html" title="backward to "13 Input
|