I/O Controller 1204: 12DI, 4DO & Serial RS-232 port over IP
4 stars based on
All input and output operations are performed through ports. A port is a pointer into a possibly infinite stream of data continuing on binary input and output a filean opening through which programs may draw bytes or characters from the stream or place bytes or characters into the stream. A port may be an input port, an output port, or both simultaneously. Ports are first-class objects, like any other object in Scheme.
Like procedures, ports do not have a printed representation the way strings and numbers do. There are initially three ports: Several ways to open new ports are provided. An input port often points to a finite stream, e. If one of the input operations, e. Ports are either binary or textual. A binary port allows a program to read continuing on binary input and output write 8-bit unsigned bytes, or "octets," from or to the underlying stream.
A textual port allows a program to read or write characters. In many cases, the underlying stream is organized as a sequence of bytes, but these bytes should be treated as encodings for characters. In this case, a textual port may be created with a transcoder to decode bytes to characters for input or encode characters to bytes for output. A transcoder continuing on binary input and output a codec that determines how characters are represented as bytes.
Three standard codecs are provided: For the latin-1 encoding, each character is represented by exactly one byte. For utf-8each character is represented by from one to four bytes, and for utfeach character is represented by two or four bytes. A transcoder also encapsulates an eol style that determines whether and how line endings are recognized. If the eol style is noneno line continuing on binary input and output are recognized.
The six other standard eol styles are the following: Unicode next-line continuing on binary input and output ls: Unicode line-separator character crlf: For input, any eol style except none causes each of the line-ending characters or two-character sequences to be converted into continuing on binary input and output single line-feed character. For output, any eol style except none causes line-feed characters to be converted into the specific one- or two-character sequence associated with the eol style.
In the input direction, all eol styles except none are equivalent, while in the output direction, the eol styles none and lf are equivalent. In addition to the codec and eol style, a transcoder encapsulates just one other piece of information: The error-handling mode is ignoreraiseor replace. If the error-handling mode is ignorethe offending sequence of bytes or the character is ignored. If the error-handling mode is continuing on binary input and outputa replacement character or character encoding is produced: A port may be buffered for efficiency, to eliminate the overhead of a call into the operating system for each continuing on binary input and output or character.
Three standard buffer modes are supported: With block buffering, input is drawn from a stream and output is sent to the stream in chunks of some implementation-dependent size. With line buffering, buffering is performed on a line-by-line basis or on some other implementation-dependent basis. Line buffering is typically distinguished from block buffering only for textual output ports; there are no line divisions in binary ports, and input is likely to be drawn from a stream as it becomes available.
With buffer-mode none, no buffering is performed, so output is sent immediately to the stream and input is drawn only as needed. Transcoders As described above, transcoders encapsulate three values: This section describes the procedures that create or operate on transcoders and the values that transcoders encapsulate. The eol-style syntax provides useful documentation as well. The error-handling-mode syntax provides useful documentation as well.
Opening Files The procedures in this section are used for opening file ports. Procedures for opening other kinds of ports, e. Each of the file-open operations accepts a path argument that names the continuing on binary input and output to be opened. It must be a string or some other implementation-dependent value that names a file.
Some of the file-open procedures accept optional optionsb-modeand? Binary ports created by the procedures in this section support the port-position and set-port-position! Whether textual ports created by the procedures in this section support these operations is implementation-dependent. There are three standard file options: With the default file options, i. If the no-fail option is included, continuing on binary input and output exception is raised if the file already exists; instead, the file is opened and truncated to zero length.
The no-create option implies the no-fail option. The no-truncate option is relevant only if the no-fail option is included or implied, in which case if an existing file is opened, it is not truncated, but the port's position is still set to the beginning of the file.
Continuing on binary input and output is perhaps easier to imagine that the default file options are the imaginary option symbols createfail-if-existsand truncate ; no-create removes createno-fail removes fail-if-existsand no-truncate removes truncate. Implementations may support additional file option symbols. The buffer-mode syntax provides useful documentation as well. Otherwise, this procedure returns a binary input port. See the lead-in to this section for a description of the constraints on and effects of the other arguments.
Otherwise, this procedure returns a binary output port. Standard Ports The procedures described in this section return ports that are attached to a process's standard input, standard output, and standard error streams.
The first set returns "ready-made" textual ports with implementation-dependent transcoders if any and buffer modes. Thus, these procedures are typically appropriate only when a program no longer needs to use any existing ports attached to the standard streams.
String and Bytevector Ports The procedures in this section allow bytevectors and strings to be used as input or output streams. The effect of modifying bytevector after this procedure is called is unspecified. The new port may or may not have a transcoder, and if it does, the transcoder is implementation-dependent. While not required, implementations are encouraged to support port-position and set-port-position! Otherwise, the port value is a binary output port. The extraction procedure is a procedure that, when called without arguments, creates a bytevector containing the accumulated bytes in the port, clears the port of its accumulated bytes, resets its position to zero, and returns the bytevector.
The accumulated bytes include any bytes written beyond the end of the current position, if the position has been continuing on binary input and output back from its maximum extent.
The accumulated characters include any characters written beyond the end of the current position, if the position has been set back from its maximum extent. Otherwise, procedure is called with a binary bytevector output port. If procedure returns, a bytevector containing the bytes accumulated in the port is created, the accumulated bytes are cleared from the port, the port's position is reset to zero, and the bytevector is returned from call-with-bytevector-output-port.
These actions occur each time procedure returns, if it returns multiple times due to the invocation of a continuation created while procedure is active. If procedure returns, a string containing the characters accumulated in the port is created, the accumulated characters are cleared from the port, the port's position is reset to zero, and the string is returned from call-with-string-output-port.
Opening Custom Ports procedure: These arguments are described below. It is called with three arguments: If the byte stream is at end of file, r! Otherwise, it should read at least one and at most n bytes from the stream, store these bytes in consecutive locations of bytevector starting at startand return as an exact positive integer the number of bytes actually read.
If it is fthe port will not support port-position. If it is not fit will be passed zero arguments and should return the current position as a displacement in bytes from the start of the byte stream as an exact nonnegative integer. If it is fthe port will not support set-port-position! If it is not fit will be passed one argument, an exact nonnegative integer representing the new position as a displacement in bytes from the start of the byte stream, and it should set the position to this value.
If it is fno action will be taken to close the byte stream when the new port is closed. If it is not fit will be passed zero arguments and should take whatever actions are necessary to close the byte stream.
For the same reason, a call to port-position after an input operation may not return an accurate position if the sp! If the character stream is at end of file, r! Otherwise, it should read at least one and at most n characters from the stream, store these characters in consecutive locations of string starting at startand return as an exact positive integer the number of characters actually read. If it is not fit will be passed zero arguments and should return the current position, which may be an arbitrary value.
If it is not fit will be passed one argument, posa value representing the new position. If pos is the result of a previous call to gpsp! If it is fno action will be taken to close the character stream when the continuing on binary input and output port is closed. If it is not fit will be passed zero arguments and should take whatever actions are necessary to close the character stream.
Since the representations of port positions are not specified, it is not possible for the implementation to adjust the gp return value to account for the number of buffered characters. For the same reason, a call to port-position after an input operation may not return an accurate position, even if the sp! It should, however, be possible to perform output reliably after reading if the position is reset to the starting position.
Port Operations This section describes a variety of operations on ports that do not directly involve either reading from or writing to a port. The input and output operations are described in subsequent sections. Once a port has been closed, no more input or output operations may be performed on the port. Because the operating system may place limits on the number of file ports open at one time or restrict access to an open file, it is good practice to close any file port that will no longer be used for input or output.