IOS_$CREATE Domain/OS IOS_$CREATE
NAME
ios_$create - create an object and open a stream to it
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/type_uids.h>
#include <apollo/ios.h>
void ios_$create(
char *pathname,
short &name_length,
uid_$t &type_uid,
ios_$create_mode_t &create_option,
ios_$open_options_t &open_options,
ios_$id_t *stream_id,
status_$t *status)
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/type_uids.ins.pas';
%include '/sys/ins/ios.ins.pas';
procedure ios_$create(
in pathname: univ name_$long_pname_t;
in namelength: integer;
in type_uid: uid_$t;
in create_option: ios_$create_mode_t;
in open_options: ios_$open_options_t;
out stream_id: ios_$id_t;
out status: status_$t);
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/type_uids.ins.ftn'
%include '/sys/ins/ios.ins.ftn'
integer*2 name_length, create_option, open_options, stream_id
integer*4 type_uid(2), status
character pathname*1023
call ios_$create(pathname, name_length, type_uid, create_option,
& open_options, stream_id, status)
DESCRIPTION
Ios_$create opens a stream to an object and creates the object if neces-
sary. Generally, if pathname specifies an object that does not exist,
ios_$create creates a new object of type type_uid at pathname and opens a
stream to it.
Creating a Temporary Object
Ios_$create can create a temporary object two ways. To create a tem-
porary object on a node's boot volume, specify a null pathname and a
namelength of 0. To create a temporary object on another volume, specify
the pathname of an existing object on that volume and the
ios_$loc_name_only_mode option in create_option. The
ios_$loc_name_only_mode option causes ios_$create to create a temporary
unnamed object on the same volume as the object at pathname.
Creating an Object in Backup Mode
If ios_$make_backup_mode is passed in create_option and an object exists
at pathname, then ios_$create creates a new temporary object with the
same attributes and on the same volume as the object at pathname. When
the temporary object is closed, the old contents of the named object are
saved in a new object with a ".bak" suffix added to its pathname. The
new object is then made permanent and given the name pathname.
If an old ".bak" version of the object already exists, ios_$close deletes
it and puts the new one in its place. If the ".bak" object is locked at
the time ios_$close is called, the old ".bak" object will be deleted when
it is unlocked.
If an object does not already exist at pathname, ios_$create creates one
with default attributes.
pathname
The location of the target object. The usual result of ios_$create
is to open a stream to a new object at pathname, but the actual
result of the call depends on the create_option argument. A null
pathname and a namelength of 0 will create a temporary object on a
node's boot volume.
namelength
The length of pathname in bytes. Specify a length of 0 to create a
temporary object on a node's boot volume.
type_uid
The type of object to create.
If type_uid is the predefined uid_$nil, ios_$create creates an
object of the default type, which is currently "unstructured"
(unstruct_$uid). Type_uid can also be any of the system's prede-
fined type unique identifiers (type UIDs) or any valid user-created
type UID.
create_option
Specifies the action to be taken if the object already exists, or
directs ios_$create to create an unnamed object. Specify one of the
following predefined values:
ios_$loc_name_only_mode
Create a temporary unnamed object on the same volume as the
existing object at pathname.
ios_$make_backup_mode
If an object exists at pathname, then ios_$create creates a new
temporary object with the same attributes and on the same
volume as the object at pathname. When the temporary object is
closed, the old contents of the named object are saved in a new
object with a ".bak" suffix added to its pathname. The new
object is then made permanent and given the name pathname.
If an old ".bak" version of the object already exists,
ios_$close deletes it and puts the new one in its place. If
the ".bak" object is locked at the time ios_$close is called,
the old ".bak" object will be deleted when it is unlocked.
If an object does not already exist at pathname, ios_$create
creates one with default attributes.
ios_$no_pre_exist_mode
Return the ios_$already_exists error code in status if an
object already exists at pathname.
ios_$preserve_mode
Preserve the contents of the object if an object with the
specified name already exists. Then open the object and posi-
tion the stream marker to the beginning of the object (BOF).
Use this mode to modify an existing object.
ios_$recreate_mode
Recreate the object if an object with the specified name
already exists. Essentially, this option deletes the existing
object and creates a new one. The new object will have the
default set of attributes for that object type.
ios_$truncate_mode
Open the object and delete the contents if an object with the
specified name already exists. Use this mode to write new data
into the location of an existing object while preserving the
attributes of the existing object.
open_options
This is a small set of options to use when opening the object.
Specify a combination of the following:
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 equivalent to setting
open_options to 0 in C and FORTRAN, or [] in Pascal.
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.
stream_id
The ID of the stream on which the object is open. Use stream_id in
subsequent calls to identify the stream opened by this call.
status
The completion status.
NOTES
Both ios_$create and ios_$open open a stream to an object. However,
ios_$create usually creates the object if it does not exist, whereas
ios_$open returns with an error if the object does not exist.