| Allegro CL version 6.2 Unrevised from 6.1 |
Arguments: stream options
Makes the connection between the stream structure and the actual device being opened, if appropriate, and completes the initialization of the stream structure adequately enough to perform operations on the stream.
device-open is called from an
:after
method on shared-initialize after the CLOS stream is
created and initialized. device-open returns true if successful and
nil
otherwise. If unsuccessful, the shared-initialize after method will
call device-close on the new
stream with :abort t
. Writers of methods on device-open must be aware that if
they call-next-method
and that
returns nil
, it means that the next-method
has failed. The primary method must either install all of the
control-character processing tables, external-formats, and instance
flags (see section Control-character Processing) or it
must call the next more general primary method to do so, modifying the
stream to specialize it after such installations, as
desired.
Allocation and/or installation of any buffers required for stream operation is also done by the device-open method which is at an appropriate specialization level for use of that buffer. If resourcing of buffers is desired, they may be passed in through make-instance/reinitialize-instance arguments, or previously installed buffers may be reused.
The device-open method must be prepared to recognize resource and change-class situations. If no filename is specified in the options list, and if no input-handle or output-handle is given, then the input-handle and output-handle slots should be examined; if non-nil, that means the stream is still open, and thus the operation being requested of device-open is a change-class. Also, a device-open method need not allocate a buffer every time it is called, but may instead reuse a buffer it finds in a stream, if it does not become a security issue.
The options argument is a list of keyword/value
pairs. It is restified list of the initargs
argument to the shared-initialize :after method (that list is
passed to device-open
unchanged). Acceptable keywords include the keyword arguments to
cl:open (the
filespec required argument to cl:open is turned into a physical pathname and
passed in the options list paired with the
keyword :filename
). The Allegro CL implementation
of cl:open has been extended
with additional named keyword arguments and also has
&allow-other-keys
so any keyword may appear as
the identifier in the options list processed by
device-open. (See the
discussion of the Allegro CL implementation of cl:open in Extensions to cl:make-package,
cl:disassemble, cl:open, cl:apropos in
implementation.htm.)
Additional named keyword arguments include:
:class
: the class argument can determine
what class to make an instance of, in the same way as in
gray-streams.
:mapped
: if :mapped t
is
specified, and the file being opened is not a fifo or
character-special file, then the file is opened using a
mapped-file-simple-stream.
:fn-in
and
:fn-out
: these are preserved for
compatibility, but are deprecated in favor of the better names,
:input-handle
and
:output-handle
.
:input-handle
and
:output-handle
: these allow the
specification of an already-opened "device", which can either be an
open file descriptor or a stream. If either of these options are used,
then cl:open should not be
called, but instead make-instance should be called with no
:filename
specified. If a handle is a stream, then
the make-instance call is said
to encapsulate the stream; the result of the make-instance call is the encapsulating stream,
and the handle is the encapsulated stream (which itself may be an
encapsulating stream).
Current unspecified device-open methods exist on all existing leaf stream classes. Device writers must determine whether it is appropriate to use the existing version, or to write one.
See streams.htm for information on the simple-streams implementation in Allegro CL. See particularly thse sections in that document: Device-open and From-scratch device-open.
Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.
| Allegro CL version 6.2 Unrevised from 6.1 |