IOS_$INTRO Domain/OS IOS_$INTRO
NAME
intro - device-independent I/O
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/type_uids.h>
#include <apollo/ios.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/type_uids.ins.pas';
%include '/sys/ins/ios.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/type_uids.ins.ftn'
%include '/sys/ins/ios.ins.ftn'
DESCRIPTION
The ios_$ calls facilitate device-independent input and output.
The following is a list of the ios_$ calls.
ios_$change_path_name change an object's pathname
ios_$close close a stream
ios_$create create an object and open a stream
to it
ios_$delete delete an object
ios_$dup duplicate a stream
ios_$equal determine if two streams are open on
the same object
ios_$force_write_file save an object to permanent storage
ios_$get read data from a stream
ios_$get_dir_lc get the current working or naming
directory
ios_$get_ec get a pointer to a stream eventcount
ios_$get_handle convert a stream ID to a handle
ios_$inq_byte_pos return the byte position of a stream
marker
ios_$inq_conn_flags return connection attributes
ios_$inq_cur_rec_len return the length of the next record
ios_$inq_file_attr get file attributes
ios_$inq_full_key return a full seek key
ios_$inq_mgr_flags return manager attributes
ios_$inq_obj_flags return object attributes
ios_$inq_path_name_lc get an object's pathname
ios_$inq_rec_pos return the record position of a
stream marker
ios_$inq_rec_remainder return the number of bytes left in a
record
ios_$inq_rec_type return the record type of an object
ios_$inq_short_key return a short seek key
ios_$inq_type_uid get the type of an object
ios_$locate get a pointer to data in a stream
ios_$open open an existing object
ios_$put write to an object
ios_$replicate replicate a stream
ios_$seek seek on a stream
ios_$seek_full_key seek with a full key
ios_$seek_short_key seek with a short key
ios_$seek_to_bof seek to the beginning of an object
ios_$seek_to_eof seek to the end of an object
ios_$set_conn_flag set connection attributes
ios_$set_dir change the current working or naming
directory
ios_$set_locate_buffer_size set the locate buffer size
ios_$set_obj_flag set object attributes
ios_$set_rec_type change an object's record type
ios_$switch switch a stream to another ID
ios_$truncate truncate an object at the current
stream marker
Every file-system object in Domain/OS that is subject to I/O has a type.
The type of an object determines which operations can be performed on the
object and the result of those operations. The IOS (I/O Switch) is a
Domain/OS facility that invokes the proper manager operation for the type
of object accessed by an I/O call. By invoking the proper type manager
based on the target object for an I/O call, the I/O Switch allows pro-
grams to perform I/O on objects without knowing their types in advance.
Inquiring about Object Attributes
When ios_$create creates an object, the object has a default set of
attributes (the default attributes depend on the type created). These
attributes fall into three categories: manager, object, and connection
attributes. Use the following calls to determine which attributes the
newly created object has:
ios_$inq_mgr_flags
Return the attributes that the object's type manager defines.
ios_$inq_obj_flags
Return the attributes of the object.
ios_$inq_conn_flags
Return the attributes of a stream connection to the object.
To change object or connection attributes, use the ios_$set_obj_flags and
ios_$set_conn_flags calls, respectively. The attributes that a program
can change depend on the object type. Note that a program cannot change
manager attributes because the type manager determines them.
Constants
ios_$max
The highest possible stream ID.
xoid_$nil
An Extended Object ID (XOID) for the uid_$nil type. In languages
that don't support constant aggregate types, xoid_$nil is declared
like a variable, but its value doesn't change. Use it for initiali-
zations and comparisons of variables of type xoid_$t.
Data Types
ios_$abs_rel_t
An enumerated type for specifying whether seeks are relative or
absolute. It takes one of the following values:
ios_$relative
Seek from the current position.
ios_$absolute
Seek from the beginning of an object (BOF) or the end of an
object (EOF).
ios_$conn_flag_t
An enumerated type for specifying a stream connection attribute. It
takes one of the following values:
ios_$cf_append
The connection's stream marker will be positioned at the end of
the object (EOF) before each output call.
ios_$cf_ipc
The connection behaves like an interprocess communication (IPC)
channel.
ios_$cf_no_read
The connection cannot be read.
ios_$cf_read_intend_write
The connection is open for read access and may later be opened
for write access. Other processes can read from the stream but
cannot write to it or get "read with intent to write" access.
ios_$cf_sequential
The connection is accessible only by sequential I/O calls.
ios_$cf_tty
The connection behaves like a terminal.
ios_$cf_unregulated
Multiple processes can write to the connection.
ios_$cf_vt
The connection behaves like a virtual terminal.
ios_$cf_write
The connection can be written to.
ios_$conn_flag_set
A set of connection attributes. The set can contain a collection of
elements of type ios_$conn_flag_t. The following mask values are
provided for C and FORTRAN programmers. In C and FORTRAN, the value
of an argument of type ios_$conn_flag_set is a logical OR of the
following masks:
ios_$cf_append_mask
The connection's stream marker will be positioned at the end of
the object (EOF) before each output call.
ios_$cf_ipc_mask
The connection behaves like an interprocess communication (IPC)
channel.
ios_$cf_no_read_mask
The connection cannot be read.
ios_$cf_read_intend_write_mask
The connection is open for read access and may later be opened
for write access. Other processes can read from the stream but
cannot write to it or get "read with intent to write" access.
ios_$cf_sequential_mask
The connection is accessible only by sequential I/O calls.
ios_$cf_tty_mask
The connection behaves like a terminal.
ios_$cf_unregulated_mask
Multiple processes can write to the connection.
ios_$cf_vt_mask
The connection behaves like a virtual terminal.
ios_$cf_write_mask
The connection can be written to.
ios_$create_mode_t
An enumerated type for modifying the result of ios_$create. It
takes one of the following values:
ios_$loc_name_only_mode
Create a new temporary unnamed object on the same volume as the
named object.
ios_$make_backup_mode
If the named object exists, create a new temporary object on
the same volume as the named object. When the temporary object
is closed, save the old contents of the named object in a new
object with a ".bak" suffix added to its name. Then make the
new object permanent and give it the name passed to
ios_$create.
ios_$no_pre_exist_mode
Return the error ios_$already_exists if the named object
exists.
ios_$preserve_mode
Open the named object but preserve its contents, and position
the stream marker at the beginning of the object (BOF). Use
this mode for modifying existing objects.
ios_$recreate_mode
Delete the named object and create a new one with default
attributes. This mode essentially tells ios_$create to ignore
the possible existence of the named object.
ios_$truncate_mode
Open the named object and truncate its contents. The object
retains its attributes but loses its contents.
ios_$dir_type_t
An enumerated type for specifying a directory. It takes one of the
following values:
ios_$ndir
The current naming directory.
ios_$wdir
The current working directory.
ios_$ec_key_t
An enumerated type for specifying which eventcount ios_$get_ec
should return a pointer to. It takes one of the following values:
ios_$get_ec_key
An eventcount that advances when data is added to the stream.
An ios_$get_rec_ec eventcount advances whenever there is some-
thing new on an open stream.
ios_$put_ec_key
An eventcount that advances when a previously full stream might
now be able to accept data.
Some objects cannot continually accept data, and streams open
to them will block an ios_$put call until they can accept data.
If stream_id belongs to such a stream, the supplied eventcount
will advance when it is possible to write data to the previ-
ously blocked stream.
ios_$id_t
A stream ID that can range from 0 to ios_$max.
ios_$mgr_flag_t
An enumerated type for specifying a type manager attribute. It
takes one of the following values:
ios_$mf_create
The manager supports the creation of objects.
ios_$mf_create_bak
The manager supports the creation of backup objects.
ios_$mf_force_write
The manager supports file system synchronization via the
ios_$force_write_file call.
ios_$mf_fork
The manager supports the exporting of streams to forked
processes created via the fork call of SysV and BSD.
ios_$mf_imex
The manager supports the exporting of streams to new processes
created via pgm_$invoke or BSD vfork.
ios_$mf_no_read
The manager supports write-only objects.
ios_$mf_read_intend_write
The manager supports "read with intent to write" access to
objects.
ios_$mf_rec_type
The manager supports a record structure. In other words, there
is a recognizable record structure to the objects of the
manager's type.
ios_$mf_seek_abs
The manager supports absolute seeking.
ios_$mf_seek_bof
The manager supports seeking to the beginning of an object
(BOF). In other words, a BOF marker is defined for objects of
the manager's type.
ios_$mf_seek_byte
The manager supports seeking to individual bytes.
ios_$mf_seek_rec
The manager supports seeking to records.
ios_$mf_seek_short
The manager supports seeking with short keys.
ios_$mf_sparse
The manager supports sparse objects. The manager allows seek-
ing and writing beyond the end of objects.
ios_$mf_truncate
The manager allows the truncation of objects.
ios_$mf_unregulated
The manager allows multiple processes to write to an object.
ios_$mf_write
The manager supports writing to objects.
ios_$mgr_flag_set
A set of type manager attributes. The set can contain a collection
of elements of type ios_$mgr_flag_t. The following mask values are
provided for C and FORTRAN programmers. In C and FORTRAN, the value
of an argument of type ios_$mgr_flag_set is a logical OR of the fol-
lowing masks:
ios_$mf_create_mask
The manager supports the creation of objects.
ios_$mf_create_bak_mask
The manager supports the creation of backup objects.
ios_$mf_force_write_mask
The manager supports file system synchronization via the
ios_$force_write_file call.
ios_$mf_fork_mask
The manager supports the exporting of streams to forked
processes created via the fork call of SysV and BSD.
ios_$mf_imex_mask
The manager supports the exporting of streams to new processes
created via pgm_$invoke or BSD vfork.
ios_$mf_no_read_mask
The manager supports write-only objects.
ios_$mf_read_intend_write_mask
The manager supports "read with intent to write" access to
objects.
ios_$mf_rec_type_mask
The manager supports a record structure. In other words, there
is a recognizable record structure to the objects of the
manager's type.
ios_$mf_seek_abs_mask
The manager supports absolute seeking.
ios_$mf_seek_bof_mask
The manager supports seeking to the beginning of an object
(BOF). In other words, a BOF marker is defined for objects of
the manager's type.
ios_$mf_seek_byte_mask
The manager supports seeking to individual bytes.
ios_$mf_seek_rec_mask
The manager supports seeking to records.
ios_$mf_seek_short_mask
The manager supports seeking with short keys.
ios_$mf_sparse_mask
The manager supports sparse objects. The manager allows seek-
ing and writing beyond the end of objects.
ios_$mf_truncate_mask
The manager allows the truncation of objects.
ios_$mf_unregulated_mask
The manager allows multiple processes to write to an object.
ios_$mf_write_mask
The manager supports writing to objects.
ios_$name_type_t
An enumerated type for specifying the type of pathname that
ios_$inq_path_name should return. It takes one of the following
values:
ios_$root_name
An absolute pathname relative to the network root directory.
Example: //node/sid/file.
ios_$wdir_name
A leaf name if the pathname can be found in the current working
directory. Otherwise, the pathname is an absolute pathname.
ios_$ndir_name
A leaf name if if the pathname can be found in the current nam-
ing directory. Otherwise, the pathname is an absolute path-
name.
ios_$node_name
A pathname relative to the node's entry directory if the path-
name exists in the node's boot volume. Otherwise, the pathname
is an absolute pathname.
ios_$node_data_flag
A leaf name if the pathname is in the current "`node_data"
directory. Otherwise, the pathname is an absolute pathname.
ios_$leaf_name
A leaf name.
ios_$resid_name
A residual name if the object has an extended name. The
returned name is the extension maintained by the stream's type
manager.
ios_$obj_flag_t
An enumerated type for specifying an object attribute. It takes one
of the following values:
ios_$of_ascii
The object contains ASCII data.
ios_$of_async
Process groups holding valid file descriptors for the object
will be asynchronously notified via a SysV or BSD SIGIO signal
(an Aegis unix_sig_$io_f fault) when nonblocking I/O (usually
input from the object) is possible.
ios_$of_cond
Input and output to the object will be performed conditionally,
as if the ios_$cond_opt was specified on each I/O call.
ios_$of_delete_on_close
The object will be deleted when all streams open on it close.
ios_$of_ftncc
The object uses FORTRAN carriage control characters.
ios_$of_mand_lock
The object will be locked during I/O operations.
ios_$of_sparse_ok
The object can be sparse. A process can seek beyond the end of
the object before writing to it.
ios_$obj_flag_set
A set of object attributes. The set contains a collection of ele-
ments of type ios_$conn_flag_t. The following mask values are pro-
vided for C and FORTRAN programmers. In C and FORTRAN, the value of
an argument of type ios_$obj_flag_set is a logical OR of the follow-
ing masks:
ios_$of_ascii_mask
The object contains ASCII data
ios_$of_async_mask
Process groups holding valid file descriptors for the object
will be asynchronously notified via a SysV or BSD SIGIO signal
(an Aegis unix_sig_$io_f fault) when nonblocking I/O (usually
input from the object) is possible.
ios_$of_cond_mask
Input and output to the object will be performed conditionally,
as if the ios_$cond_opt_mask was specified on each I/O call.
ios_$of_delete_on_close_mask
The object will be deleted when all streams open on it close.
ios_$of_ftncc_mask
The object uses FORTRAN carriage control characters.
ios_$of_mand_lock_mask
The object will be locked during I/O operations.
ios_$of_sparse_ok_mask
The object can be sparse. A process can seek beyond the end of
the object before writing to it.
ios_$open_options_t
A small set of options available when opening an object. It takes a
combination of the following values:
ios_$inquire_only_opt
Open the object for attribute inquiries only.
ios_$no_open_delay_opt
Return immediately rather than waiting for the open operation
to complete.
ios_$no_open_options
Permit reading the object only. This is the default, and is
equivalent to specifying no options.
ios_$no_read_opt
Do not permit reading the object.
ios_$position_to_eof_opt
Move the stream marker to the end of the stream before each put
call. This overrides the implicit setting of the stream marker
in ios_$preserve_mode.
ios_$read_intend_write_opt
Open the object for read access, and allow other processes to
read it but not write to it or get "read with intent to write"
access.
ios_$unregulated_opt
Permit multiple processes to write to the object.
ios_$write_opt
Permit writing to the object.
ios_$pos_opt_t
An enumerated type for specifying a position in an object. It takes
one of the following values.
ios_$bof
The beginning of the object (BOF).
ios_$current
The current position of the stream marker.
ios_$eof
The end of the object (EOF).
ios_$put_get_opts_t
This is a small set of options to use when reading from or writing
to an object. Its value is a logical combination of the following
elements:
ios_$cond_opt
Read or write only if the stream can support the operation
immediately. If the stream is full or empty and the call would
be blocked, return with a ios_$get_conditional_failed or
ios_$put_conditional_failed completion status.
ios_$no_put_get_opts
This is the default and is included for languages that lack
Pascal set types. It is equivalent to specifying [] in Pascal.
ios_$no_rec_bndry_opt
Ignore boundaries in the data. The caller can use this option
if it is not interested in any data groupings supported by the
object type.
ios_$partial_record_opt
Write only a partial record. Unless this option is specified,
a write operation terminates the current record before return-
ing.
ios_$preview_opt
Do not update the stream marker after the operation.
ios_$rtype_t
An enumerated type for specifying record formats. It takes one of
the following values:
ios_$explicit_f2
Fixed-length records that ios_$put cannot implicitly change to
variable-length records. An attempt to write records of dif-
ferent lengths to an object with this record type will fail.
ios_$f1
Fixed-length records without count fields. Attempts to write
records of different lengths to an object with this record type
will fail.
ios_$f2
Fixed-length records with count fields. This is the default
record type. An attempt to write a record of a different
length to an object with this record type implicitly changes
the object's record type to ios_$v1.
ios_$undef
No record structure.
ios_$v1
Variable-length records with count fields.
ios_$seek_key_t
A full seek key. Full seek keys allow seeking into records.
ios_$seek_type_t
An enumerated type for specifying whether a seek is record oriented
or byte oriented. It takes on one of the following values.
ios_$rec_seek
A record-oriented seek.
ios_$byte_seek
A byte-oriented seek.
xoid_$t
An extended unique identifier (XOID) for an object. Values of type
xoid_$t are normally used only by type managers. An XOID has the
following format:
15 0
______________________________________________________________
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
______________________________________________________________
15 0
reserved
Reserved for the I/O Switch and type manager.
uid A unique identifier for an object. This element has type
uid_$t.