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.
ERRORS
ios_$already_exists
The object already exists, and ios_$no_pre_exist was specified on
ios_$create.
ios_$bad_char_seek
Attempted a character seek before start of current (variable length)
record.
ios_$bad_count_field_in_file
The count field for the current record is bad.
ios_$bad_file_hdr
The file header is no good.
ios_$bad_location
A bad location was specified in an ios_$create call.
ios_$bad_open_XP
Attempted to use open_XP to reference a stream that had not already
been opened by the calling process.
ios_$bad_shared_cursor_refcnt
The reference count on a shared file cursor went below zero.
ios_$BOF_err
Attempted seek beyond beginning of object (BOF).
ios_$buffer_too_big
The buffer is too large for the object's manager to support.
ios_$cant_change_type
Cannot change the object's type as requested by ios_$create.
ios_$cant_initialize
Cannot initialize an object of this type.
ios_$cant_set_advisory_lock
An advisory lock was already set by someone else.
ios_$concurrency_violation
The requested access violates concurrency constraints.
ios_$deadlock_detected
A deadlock condition would result from attempted record lock.
ios_$device_must_be_local
Cannot open a stream to a remote device.
ios_$dir_not_found
The directory specified in the pathname does not exist.
ios_$end_of_file
Encountered an end of file condition.
ios_$file_not_empty
Cannot change type of object because it is not empty.
ios_$flag_not_supported
Requested flag is not supported by the object's manager.
ios_$from_id_not_open
Stream ID passed to ios_$switch is not open.
ios_$get_conditional_failed
A conditional get operation found no data.
ios_$id_oor
Supplied stream ID is out of range or invalid.
ios_$illegal_name_redefine
Name change requested by ios_$change_path_name would require copying
the object.
ios_$illegal_obj_type
The object type does not support stream operations.
ios_$illegal_operation
The stream does not support the requested operation.
ios_$illegal_pad_create_type
Cannot create a pad for the object.
ios_$illegal_param_comb
Illegal parameter combination for the requested operation.
ios_$illegal_w_var_lgth_recs
The requested operation is illegal on objects with variable-length
records.
ios_$inq_only_error
The object was opened for attribute inquiry only.
ios_$insuff_memory
Not enough virtual memory to complete call.
ios_$insufficient_rights
The process has insufficient rights for requested access to object.
ios_$internal_fatal_err
Internal fatal error on table re-verification.
ios_$internal_mm_err
Internal fatal error in stream memory management.
ios_$invalid_data
The supplied data is invalid for writing to an object of this type.
ios_$name_not_found
The pathname does not exist.
ios_$name_reqd
Called ios_$open without specifying a pathname.
ios_$need_move_mode
Ios_$locate operation refused, try ios_$get.
ios_$never_closed
The object was not closed completely due to a system or process
crash.
ios_$no_advisory_lock_set
There is no advisory lock set on the object.
ios_$no_avail_target
There is no available target stream for ios_$switch to switch to.
ios_$no_more_streams
There are no more streams available.
ios_$no_rights
Calling process has no rights to access the object.
ios_$not_a_directory
The pathname specfied is not a directory.
ios_$not_at_rec_bndry
Ios_$inq_short_key is only legal at record boundaries.
ios_$not_open
The stream is not open.
ios_$not_thru_link
Cannot create an object through a link.
ios_$obj_deleted
The object was deleted while open.
ios_$object_not_found
No object exists at pathname.
ios_$object_read_only
Cannot open the object for writing.
ios_$out_of_shared_cursors
The per-mode shared file cursor pool is exhausted.
ios_$perm_file_needs_name
Only temporary files may be unnamed.
ios_$put_bad_rec_len
Attempted to ios_$put a record with the wrong length.
ios_$put_conditional_failed
A conditional put failed because the stream is full.
ios_$read_only_err
Attempted to write to a read-only stream.
ios_$resource_lock_err
Unable to lock the resources required to process request.
ios_$sio_not_local
Cannot open a remote SIO line. Can only do streams operations on
local SIO lines.
ios_$something_failed
Cannot locate manager, connection, or object attributes. Cannot
change or report on attribute set.
ios_$target_inuse
The target stream ID passed to ios_$switch is already in use, and
there are no other available stream IDs.
ios_$write_only_err
Attempted to read a write-only stream.
ios_$xp_buf_too_small
The buffer supplied to get_xp is too small.
WARNINGS
ios_$part_rec_warn
Record not completed at EOF when stream closed.
ios_$cant_delete_old_name
The new name was added but can't delete the old one.
ios_$buffer_too_small
The buffer is too small for the requested ios_$get or ios_$locate.
ios_$full_rec_unavail
A full record was requested by ios_$get, but only part of the record
was available. The available part was returned, but there is still
more room in the buffer.