7.2 Input/Output system extensions

7.2.9 Reference pages

Syntax:buffer-ref buffer index element-type

The macrobuffer-ref obtains the element with the specified index from a buffer defined in the buffered interface.

The buffer argument is a buffer returned by the function get-input-buffer,get-input-buffer-no-hang, orget-output-buffer.

The index argument is an integer that specifies the element of the buffer that the macro should return.

The element-type argument specifies the internal element type used in the buffered stream. It must be one of the typesstring-char,character, (unsigned-byte n), or (signed-byte n); generally, it is the same type that is specified to the Common Lisp functionopen.

If you do not know the element type of the stream you are using, call the Common Lisp functionstream-element-type on the stream.

See Also: get-input-buffer, get-input-buffer-no-hang, get-output-buffer;stream-element-type (in CLtL2)

Syntax:close-all-files

The functionclose-all-files closes all open files.

This function can be used to close files for which the associated stream object is no longer accessible.

extract-stream-handles Function

Syntax:extract-stream-handle common-lisp-stream&optional direction

Syntax:extract-stream-handles common-lisp-stream

The functionextract-stream-handle returns the file handle that the specified Common Lisp stream uses for the specified input or output direction. The functionextract-stream-handles returns the file handles that the given Common Lisp stream uses for input and output. A file handle is a UNIX file descriptor. For LCL/HP and LCL/RS6000, the file handle is an operating system stream identifier, which is equivalent to a UNIX file descriptor.

These functions use the functionunderlying-stream to retrieve the stream whose file handle or handles are returned.

If you do not specify the optional direction argument toextract-stream-handle, the direction specified when the stream was opened is used. It is an error to specify a direction that common-lisp-stream is not open for.

The functionextract-stream-handles always returns two values, the file handles used for input and output. For unidirectional streams, one of the returned values isnil, which indicates that there is no associated file handle for that direction.

common-lisp-stream can be any stream that has one or more file handles. Streams createdwith make-lisp-stream must have at least one file handle, so that callingextract-stream-handles on such a stream will return at least one non-nil value. Callingextract-stream-handles on a stream created in some other way that does not have any file handles at all will cause an error.

Note: You should not perform input or output operations that involve both the file handles and the Common Lisp stream associated with them. Doing so can cause unpredictable results.

;; First, define a function that invokes the UNIX OPEN library call.
> (def-foreign-function (unix-open (:name "_open")) path flags mode)
UNIX-OPEN

> (load-foreign-libraries nil)
NIL
;; Get a UNIX file descriptor on the terminal for output.
> (setq fd (unix-open "/dev/tty" 1 0))
3

;; Now create a Lisp stream which does output to this file handle.
> (setq str (make-lisp-stream :output-handle fd))
#<Stream OSI-BUFFERED-STREAM E6976B>

;; Get the handles from the stream.  There is no input handle, and 
;; the output handle is the value of the variable FD.
> (extract-stream-handles str)
NIL
3

;; You can get the output handle this way as well.
> (extract-stream-handle str :output)
3

;; Write some text to the stream.
> (format str "text~%")
NIL

;; Force the output to actually be printed.
> (force-output str)
text
NIL

;; Close the stream when done.
> (close str)
NIL

See Also: make-lisp-stream, underlying-stream

fast-unread-char Macro

fast-write-char Macro

fast-write-string Macro

fast-read-byte Macro

fast-write-byte Macro

Syntax:fast-read-char stream eof-error-p eof-value

Syntax:fast-unread-char char stream

Syntax:fast-write-char char stream

Syntax:fast-write-string string stream&key :start :end

Syntax:fast-read-byte stream type eof-error-p eof-value

Syntax:fast-write-byte byte stream type

These macros expand into in-line code, and for I/O operations involving simple streams, they are faster than their functional counterparts. If the input or output stream is not a simple stream, the performance of these macros is equivalent to the performance of the related Common Lisp functions (read-char,unread-char,write-char,write-string, read-byte,write-byte).

These macros do not perform type checking, so you must guarantee that the stream argument is a stream that is open for I/O in the correct direction and that all other arguments are of the correct type. The stream argument can be any stream type; however, if you use a composite stream rather than simple stream, the performance will be slower. The functionunderlying-stream returns the lowest level stream of a composite stream.

The type argument for the byte operations specifies the type of byte for which the stream is open. Any argument that is valid as an:element-type option for the Common Lisp functionopen is acceptable. You do not need to quote this argument.

Note that the default value of the Common Lisp variable*terminal-io* is a composite stream with separate input and output directions. Thus, it does not meet the conditions for fast I/O.

When the corresponding functions are called simultaneously in two processes to perform input and output operations to the same stream, they use a locking mechanism to prevent data-structure corruption. If you use one of these macros on the same stream in two processes, the results are unpredictable.

;; Write the numbers from 0 to 2 to an 8-bit binary file.
> (with-open-file (f "temp.out" :direction :output
                                :element-type '(unsigned-byte 8))
    (dotimes (i 3)
      ;; Note element-type here.
      (fast-write-byte i f (unsigned-byte 8))))
NIL

;; Read a file, and type out the characters until EOF is reached.
> (with-open-file (f "temp.out")
     (loop
      (let ((char (fast-read-char f nil)))
        (unless char (return nil))
        (write-char char))))
NIL

get-input-buffer-no-hang Function

get-output-buffer Function

Syntax:get-input-buffer &optional stream eof-error-p eof-value

Syntax:get-input-buffer-no-hang &optional stream eof-error-p eof-value

Syntax:get-output-buffer &optional stream

The functionsget-input-buffer,get-input-buffer-no-hang, andget-output-buffer give you access to an I/O buffer that is used by a stream so that you can read or modify the buffer directly. They return the following values:

• The first value returned is a buffer, which is an array of data that is read from the stream or is available for data to be written. If no buffer is immediately available,get-input-buffer-no-hangreturnsnil and no other values.

• The second value is an index, which is an integer that indicates the position in the array that holds or can hold the next element.

• The last value is the limit, which is an integer that indicates the first element that follows the valid portion of the buffer. You cannot modify the buffer at or beyond this point.

If you do not specify the stream argument, the stream that is the value of the Common Lisp variable*standard-input* is used for the functions get-input-buffer andget-input-buffer-no-hang; the stream that is the value of*standard-output* is used forget-output-buffer. If you specify the valuet for the stream argument, the stream that is the value of*terminal-io* is used.

If an end-of-file occurs before a character can be read, an error is signaled if eof-error-p has a non-nil value; this value is the default. If an end-of-file occurs and the value of eof-error-p isnil, no error is signaled and eof-value is returned. The default value of eof-value isnil.

To extract elements from the buffer, use the macrobuffer-ref. To add elements to the buffer, use the Common Lisp macrosetf with buffer-ref.

Once you have finished with the buffer obtained by these functions, you must use the functionreturn-input-buffer orreturn-output-buffer to restore the buffer to the stream in most instances.

If the stream argument performs input and output operations to the same file, you do not have to return the buffer in the same way that you obtained it. In this case, you should adhere to the following guidelines:

• Useget-input-buffer if you want to be informed of an end-of-file condition.

• Useget-output-buffer if you want to write into an empty buffer when an end-of-file condition occurs.

• Usereturn-output-buffer if you want to write the data you have modified in the buffer into a file.

• Usereturn-input-buffer if you have not modified the buffer. However, do not usereturn-input-buffer to abort modifications you have made to the buffer.

If you do not want to save the changes you have made to the buffer, you should invoke the Common Lisp functionclose on the stream and specify a non-nil value for the:abort keyword argument.

For bidirectional streams,get-output-buffer returns a buffer that contains only data read from the stream or uninitialized data that will be appended to the end of the stream. You cannot extend a bidirectional stream by adding data to the end of the buffer; you must return the buffer and obtain an empty buffer to add data to the stream.

See Also: buffer-ref, return-input-buffer, return-output-buffer

Syntax:*ignore-extra-right-parens*

The variable*ignore-extra-right-parens* controls the action of the reader when excess right parentheses are encountered in the input stream. The action taken depends on the value of the variable as follows:

• If the value ist, excess right parentheses in the input stream are ignored.

• If the value is:just-warn, a warning message is generated.

• If the value isnil, a continuable error is signaled.

The initial value of*ignore-extra-right-parens* is:just-warn.

> *ignore-extra-right-parens*
:JUST-WARN
> (read-from-string ")1")
;;; Warning: Ignoring an unmatched right parenthesis.
1
2

> (let((*ignore-extra-right-parens* t))
      (declare (special *ignore-extra-right-parens*))
    (read-from-string ")1"))
1
2

Syntax:make-lisp-stream&key :input-handle :output-handle :io-handle :element-type :auto-force :positionable :desired-buffer-size

The functionmake-lisp-stream constructs a Common Lisp stream from file handles. A file handle is a UNIX file descriptor. For LCL/HP and LCL/RS6000, the file handle is an operating system stream identifier, which is equivalent to a UNIX file descriptor.

This function accepts the following keyword arguments:

• :input-handle

This keyword argument specifies a file handle for a device that is opened for input. If you supply this argument, a Common Lisp input stream is constructed.

• :output-handle

This keyword argument specifies a file handle for a device that is opened for output. If you supply this argument, a Common Lisp output stream is constructed.

• :io-handle

This keyword argument specifies a file handle for bidirectional data transfers. Use this keyword only for disk files opened for both read and write. If you supply this argument, a bidirectional stream with a single file pointer and buffer is constructed. Whenever you read or write a byte to such a stream, the pointer is advanced by one position; this behavior is the same as with a file that is opened with:direction :io.

• :element-type

This keyword argument gives the element type that is associated with the stream; any argument that is valid as an:element-type option for the Common Lisp functionopen is acceptable. The default value is'string-char.

• :auto-force

If this keyword argument has a non-nil value, the stream forces output after each output operation. The default value isnil.

• :positionable

If this keyword argument has a non-nil value, you can use the Common Lisp functionfile-position to change the pointer position in the stream; in this case, the Common Lisp functionsclear-input andclear-output have no effect on the stream that is created. Disk files are generally positionable, but terminal and network connections generally are not.

If the value of this argument isnil, you cannot set the position of the file pointer withfile-position. If invoked, clear-input andclear-output attempt to clear input and output on the stream respectively. The default value isnil.

• :desired-buffer-size

This keyword argument specifies the number of elements that should be used for buffers for this stream. If you do not specify this argument, a reasonable size for the element type is used.

To make a bidirectional Common Lisp stream with separate file pointers, separate input and output openings, and separate buffers, specify different file handles for the:input-handle and:output-handle options. You should use this method for creating bidirectional streams if the file handles are associated with a socket or a similar device. If you have a device such as a terminal or network connection that has a single handle for both input and output, specify that handle as the value of both the:input-handle and:output-handle keyword arguments.

;; First, define a function that invokes the UNIX OPEN library
;; call.
> (def-foreign-function (unix-open (:name "_open")) 
          path flags mode)
UNIX-OPEN

;; Get a UNIX file descriptor on the terminal for output.
> (setq fd (unix-open "/dev/tty" 1 0))
3

;; Now create a Lisp stream that does output to this file handle.
> (setq str (make-lisp-stream :output-handle fd))
#<Stream OSI-BUFFERED-STREAM E6976B>extract-stream-handle

See Also: extract-stream-handle, extract-stream-handles,with-buffered-terminal-output

Syntax:*print-structure*

The variable*print-structure* controls the printing of structures.

If the value of*print-structure* is non-nil, structures are printed in detail, using the#S syntax. If*print-structure* isnil, they are printed with the abbreviated#<...> syntax. The initial value of*print-structure* is t.

> *print-structure*
T

> (defstruct family mom dad brother sister dog)
FAMILY

> (setq jones (make-family :mom 'simone :dad 'sam 
                           :brother 'basket-ball
                           :sister 'sally :dog 'bowser))
#S(FAMILY MOM SIMONE DAD SAM BROTHER BASKET-BALL SISTER SALLY DOG BOWSER)

> (let ((*print-structure* nil)) (print jones) (values))
#<Structure FAMILY 428F3B>

write-array Function

Syntax:read-array stream array&optional start end eof-error-p eof-value

Syntax:write-array stream array&optional start end

The functionsread-array andwrite-array read and write respectively the contents of the specified one-dimensional array into the specified stream.

The elements stored in the array to be written or read must be of a type that is acceptable as an:element-type argument to the Common Lisp functionopen.

The array argument must be a one-dimensional array.

The optional start and end arguments are integer values that specify elements of the array. The start argument marks the beginning element that is read or written; the end argument marks the element following the last element that is read or written. The start value defaults to 0; the end value defaults to the length of the array.

If an end-of-file occurs inread-array before an element can be read, an error is signaled if eof-error-p has a non-nil value; this value is the default. If an end-of-file occurs and the value of eof-error-p isnil, no error is signaled and eof-value is returned. The default value of eof-value isnil.

return-output-buffer Function

Syntax:return-input-buffer&optional stream limit-reached

Syntax:return-output-buffer&optional stream limit-reached

The functionsreturn-input-buffer andreturn-output-buffer return buffers to the specified stream.

The buffer that is returned is obtained by using the functionsget-input-buffer,get-input-buffer-no-hang, orget-output-buffer.

If you do not specify the stream argument, the stream that is the value of the Common Lisp variable*standard-input* is used for the function return-input-buffer; the stream that is the value of*standard-output* is used forreturn-output-buffer. If you specify the valuet for the stream argument, the stream that is the value of*terminal-io* is used.

The limit-reached argument is an integer that specifies the exclusive end of the buffer from which you read or to which you wrote.

If the stream argument performs input and output operations to the same file, you do not have to return the buffer in the same way that you obtained it. In this case, you should adhere to the following guidelines:

• Useget-input-buffer if you want to be informed of an end-of-file condition.

• Useget-output-buffer if you want to write into an empty buffer when an end-of-file condition occurs.

• Usereturn-output-buffer if you wish to write the data you have modified in the buffer into a file.

• Usereturn-input-buffer if you have not modified the buffer. However, do not usereturn-input-buffer to abort modifications you have made to the buffer.

See Also: get-input-buffer, get-input-buffer-no-hang, get-input-buffer, get-output-buffer

Syntax:underlying-stream stream&optional direction recurse exact-same-effect

The functionunderlying-stream returns the lowest level stream from which the specified composite stream performs I/O operations in the specified direction.

If the stream argument is a simple stream,underlying-stream returns that stream.

The direction argument can be any of the directions:input,:output, or:io. If you do not specify the direction argument or if you specify the valuenil, the lowest level stream that receives all I/O operations is returned.

If the value of the recurse argument isnil, there will be only one level of indirection. Having only one level of indirection is useful if, for example, you need to get the stream from which a two-way stream is made, even if that component stream is composite. The default value of recurse ist.

If the exact-same-effect argument has a non-nil value, you can perform I/O operations in the given direction to the stream that is returned and be assured of getting the exact same effect as if you had performed the operations to the higher level stream. For example, if stream is an echo stream and direction is:input, setting exact-same-effect returns the echo stream because performing an input operation from the input stream directly would not produce echoing.

If you specify a composite stream for the stream argument, the behavior ofunderlying-stream depends on the stream type:

• echo,two-way
  • direction is:input and exact-same-effect isnil, or direction is:output.

  In these cases,underlying-stream follows the stream in that direction and returns the lowest level stream.

  • direction is:input; exact-same-effect ist.

  underlying-stream behaves as if the argument is a simple stream.

• synonym

A synonym stream is always followed, and the lowest level stream is returned.

• broadcast,concatenated

The behavior with these types of streams is the same as with simple streams.

See Also:make-broadcast-stream,make-concatenated-stream,make-echo-stream,make-synonym-stream,make-two-way-stream (in CLtL2)

Syntax:with-buffered-terminal-output stream {form}*

The macrowith-buffered-terminal-output suppresses automatic forcing of output after each output operation. The output to the stream is sent to the terminal when the last output operation is complete.

The body of the macro is specified by the form arguments, which are executed in order. The value of the last form that is executed is returned as the result of executing the macro.

This macro works with terminal input and output and with streams created with the functionmake-lisp-stream using the:auto-force keyword option.

Use this macro to obtain better performance when you must execute a group of output operations. This macro is used internally by output operations such as those performed by the Common Lisp functionsprint andformat.

See Also: make-lisp-stream

Generated with Harlequin WebMaker