Multics Technical Bulletin MTB-553 Revision 1
DM: File Spec
To: Distribution
From: André Bensoussan & Jeffrey D. Ives & R. Michael Tague
Date: 07/06/84
Subject: Data Management: File Manager Specifications
ABSTRACT
This document describes the functions provided by the data
management file manager. For each of these functions, a
description of what the function accomplishes, and what the
caller of the function is supposed to know is given. The
description of how the function accomplishes its task is in the
file manager design document, MTB 554.
Revision 1 of this document contains documentation on more than |
30 additional entry points. Many of these new entry points are |
for setting and getting access control, ring, and directory name |
information. |
Comments should be sent to the author:
via Forum:
>udd>Multics>Spratt>mtgs>DMS_Development.
via Multics Mail:
Tague.Multics on either System M or MIT Multics.
via telephone:
HVN (617) 492-9358
_________________________________________________________________
Multics project internal working documentation. Not to be
reproduced or distributed outside the Multics project without the
consent of the author or the author's management.
CONTENTS
Page
Abstract . . . . . . . . . . . . . . . i
1 Introduction . . . . . . . . . . . . 1
2 Characteristics of a data management
file . . . . . . . . . . . . . . . . 1
2.1 Naming . . . . . . . . . . . . 1
2.2 Access control . . . . . . . . 1
2.3 Control intervals . . . . . . . 2
2.4 Capacity . . . . . . . . . . . 2
2.5 File accessing . . . . . . . . 3
2.6 Protected data management files 3
2.7 Unprotected files . . . . . . . 4
3 File manager primitives . . . . . . 4
file_manager_ . . . . . . . . . . . 5
$abandon . . . . . . . . . . . . 6
$add_acl_entries . . . . . . . . 7
$adopt . . . . . . . . . . . . . 9
$allocate . . . . . . . . . . . 10
$chname_file . . . . . . . . . . 11
$close . . . . . . . . . . . . . 12
$copy . . . . . . . . . . . . . 13
$create . . . . . . . . . . . . 15
$create_open . . . . . . . . . . 18
$delentry_file . . . . . . . . . 19
$delete_acl_entries . . . . . . 20
$delete_close . . . . . . . . . 22
$end_of_crash_recovery . . . . . 23
$find_old_uid_pn_table . . . . . 24
$flush_consecutive_ci . . . . . 25
$flush_modified_ci . . . . . . . 26
$free . . . . . . . . . . . . . 27
$get . . . . . . . . . . . . . . 28
ci_parts structure . . . . . . . 29
$get_ci_header . . . . . . . . . 31
ci_header structure . . . . . . 31
$get_ci_ptr . . . . . . . . . . 33
$get_exclusive . . . . . . . . . 35
$get_max_length . . . . . . . . 36
$get_ring_brackets . . . . . . . 37
$get_stream . . . . . . . . . . 38
$get_switch . . . . . . . . . . 39
$get_user_access_modes . . . . . 40
CONTENTS (cont)
Page
$list_acl . . . . . . . . . . . 42
$list_switches . . . . . . . . . 43
$lock_advice . . . . . . . . . . 45
$open . . . . . . . . . . . . . 47
$open_by_uid . . . . . . . . . . 49
$open_by_uid_after_crash . . . . 50
$per_system_init . . . . . . . . 51
$post_commit . . . . . . . . . . 52
$prepare_to_copy . . . . . . . . 53
$put . . . . . . . . . . . . . . 54
$put_journal . . . . . . . . . . 56
$put_stream . . . . . . . . . . 57
$raw_get . . . . . . . . . . . . 58
$raw_put . . . . . . . . . . . . 59
$replace_acl . . . . . . . . . . 60
$set_ring_brackets . . . . . . . 61
$set_switch . . . . . . . . . . 62
$simple_get . . . . . . . . . . 63
$simple_put . . . . . . . . . . 64
$status . . . . . . . . . . . . 65
$suffix_info . . . . . . . . . . 66
copy_flags . . . . . . . . . . . 67
$terminate_ci_ptr . . . . . . . 69
$undo . . . . . . . . . . . . . 70
$unput . . . . . . . . . . . . . 71
$user_shutdown . . . . . . . . . 72
$validate . . . . . . . . . . . 73
Multics Technical Bulletin MTB-553 Revision 1
DM: File Spec
1 INTRODUCTION
An overview of the file access layer is in MTB 511, which
describes data management files, their position in the data
management architecture, and the services provided by the file
manager.
This document is more detailed and more specific than the
overview. It contains the functional specifications of the file
manager, given in terms of the entire set of entry points it
provides to the rest of the system. For each entry point, a
complete description of the calling sequence is given, with a
full description of what the entry point does, and anything the
caller is supposed to know to be able to make proper use of it.
2 CHARACTERISTICS OF A DATA MANAGEMENT FILE
Like a segment, a data management file is an object that
resides in the Multics hierarchy. It has a name, a directory
entry and an access control list. Data can be stored into it and
retrieved from it. Unlike a segment, it is generally accessed
though software by file manager calls, although individual
control intervals of a Data Management (DM) file can be read by
direct memory reference. DM files are capable of being much
larger than a segment.
2.1 Naming
Like a segment, a data management file is found in the
Multics hierarchy by its pathname. All pathname conventions that
apply to segments also apply to data management files; except, if
you change its name or the names of any of its parent
directories, the mechanisms that protect it from process and
system failure may not work for the rest of the bootload.
A data management file is ring 2 multisegment file (MSF). A
file with the pathname >A>B>C>F will be materialized by the
directory >A>B>C>F in which MSF components will be created as
needed.
MTB-553 Revision 1 Multics Technical Bulletin
DM: File Spec
2.2 Access control
Like a segment, the list of users allowed to use a data
management file is defined in an Access Control List (ACL). The
access modes are read and write. During the period that data
management files are implemented as MSFs, all MSF components will
have identical ACLs.
2.3 Control intervals
A data management file is made of logically contiguous fixed
size blocks called control intervals. They are the unit of data
transfer from disk to main memory and from main memory to disk.
All control intervals in a file are the same size; but different
files may have different control interval sizes. Control
intervals within a file are designated by consecutive integers,
starting from zero.
Each control interval has a four word header and a two word
trailer. These are used by the file manager to identify the
control interval and to help implement the protection mechanism.
They are not within the addressable portion of the control
interval. The file manager has a special entry point for reading
the header. The trailer is the same as the first two words of
the header.
While data management files are implemented as multisegment
files, the only size available for control intervals will be 4096
bytes. After the 24 bytes taken up by the header and trailer,
4072 bytes are left for data storage. Control interval zero has
3176 bytes for data storage because file attributes are stored
there. Data within a control interval is addressed by its byte
offset and length. The offset of the first addressable byte is
zero. It is the first byte after the header. The file manager
does not permit applications to address data in the header,
trailer, or the file attribute area in control interval zero.
2.4 Capacity
Data management files have large capacities. During the MSF
implementation, the limit will come from the maximum number of
entries in an MSF directory, which is about 2000. This limits
the size of a data management file to about 2*10**9 bytes. In
the, so called, large file implementation, the limit will be
about 10**12 bytes, using larger control intervals. The capacity
Multics Technical Bulletin MTB-553 Revision 1
DM: File Spec
can be even greater if the application can use control intervals
larger than 10**4 bytes.
2.5 File accessing
Before accessing a data management file within a process,
you must open it and obtain an opening identifier. This protocol
is comparable to introducing a segment to a process by obtaining
a segment number with which it can be referenced. Segment
numbers can be used for direct hardware access to a segment. An
opening identifier can only be used for indirect software access
through primitives provided by the file manager. Though a direct
pointer to a specific control interval may be obtained via
get_ci_ptr, it may only be used for reading a control interval.
A data management file must be accessed through the get and
put primitives in the file manager. The get entry point copies
data from the data management file into the user's buffer. The
put entry point copies data from the user's buffer into the file.
The file manager does not associate any meaning to the data
stored in the file. Its function is to provide access in the
same way a disk controller provides access to a disk. The caller
of the get and put primitives refers to the data by its file
opening id, control interval number, byte offset, and length.
2.6 Protected data management files
The meaning of protection is abstract. Protection does not
imply any specific mechanism such as locking or journaling. It
does imply that data in the files are protected against
inconsistency caused by concurrent access and transaction
failure. It enables applications to transform data from one
consistent state to another by delimiting groups of operations
into transactions that appear atomic to other processes.
Protection against concurrent access can be turned off for
applications that do not need it. Protection against
inconsistency caused by transaction failure can also be disabled.
o Transaction mode: A protected file can only be accessed by
processes in transaction mode. Any attempt to read or modify
a protected file by a process not in transaction mode causes
an error to be returned. As a reminder to the reader, a
process is said to be in transaction mode if it has executed a
begin transaction operation but has not yet executed the
commit or abort operation that would end the transaction (See
MTB 555, Transaction Manager Spec).
MTB-553 Revision 1 Multics Technical Bulletin
DM: File Spec
o Concurrency: The system makes transactions appear atomic with
the concurrency control capability, which prevents
simultaneous transactions in different processes from
interfering with one another. The file manager's contribution
in providing this service is to automatically lock control
intervals of protected files on behalf of the transactions
that reference them. It does this for all protected files,
except for those with the "no_concurrency" option.
o Rollback: The system provides protection against transaction
failure with the rollback capability. Whenever a control
interval is modified, the file manager logs a copy of the
data, prior to modification. It does so automatically for all
protected files except for those with the "no_rollback"
option. These before images are logged in the before journal
associated with the current transaction. If the application,
the process, or the system fails, these before images are used
to restore the content of the control intervals and thus undo
the effects of the transaction on protected files.
The fact that a data management file is protected is recorded as
an attribute of the file. It is usually set when the file is
created, but it can also be set by an administrative request. A
protected file has two subattributes which indicate whether or
not concurrency or rollback have been turned off. These
subattributes are usually set when the data management file is
created, but they can be changed by an administrative request.
2.7 Unprotected files
A data management file which does not have the protected
attribute is "unprotected". This means that it does not get the
attention of the integrity services, and the system does not
provide concurrency control or rollback capabilities when the
file is used. An unprotected file may be used by a process
whether or not the process is in transaction mode.
3 FILE MANAGER PRIMITIVES
All file manager primitives are provided as entry points in
the file_manager_ module. This module is described below, in the
standard format used for MPM documentation.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Name: file_manager_
The file_manager_ module provides an entry point for each File
Manager primitive. Most entry points are for manipulating DM
files, while a few of the entries are for exclusive use by the
Data Management system in the inner ring.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$abandon
| This entry point is called by the transaction manager when the
| transaction manager has been called to abandon a transaction.
| The effect of this call is to discard the list of pages that
| would be flushed by the file manager to commit a transaction. It
| is assumed that the abandoned transaction will be adopted by the
| Data Management daemon and rolled back.
| Usage
| dcl file_manager_$abandon entry (bit(36) aligned, fixed bin,
| fixed bin(35));
| call file_manager_$abandon (txn_id, txn_idx, code);
| where:
| txn_id (Input)
| is the transaction identifier of the current
| transaction.
| txn_idx (Input)
| is the corresponding index into the TDT for the
| current transaction.
| code (Output)
| is the standard system status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$add_acl_entries |
This entry point adds the specified access modes to the access |
control list (ACL) of the specified Data Management (DM) file. |
If the access name already appears on the ACL of the DM file, its |
mode is changed to the one specified by the call. The legal |
access modes for a DM file are: null, read, and read/write. |
Usage |
dcl file_manager_$add_acl_entries entry (char(*), char(*), |
ptr, fixed bin, fixed bin(35)); |
call file_manager_$add_acl_entries (dir_name, entryname, |
acl_ptr, acl_count); |
where: |
dir_name (Input) |
is the pathname of the containing directory. |
entryname (Input) |
is the entryname of the DM file. |
acl_ptr (Input) |
points to a user-supplied segment_acl structure |
(described under "Notes" below). |
acl_count (Input) |
is the number of ACL entries in the segment_acl |
structure. |
code (Output) |
is the standard system status code. |
Notes |
The following is the segment_acl structure (declared in |
acl_structures.incl.pl1): |
dcl 1 segment_acl (acl_count) aligned based (acl_ptr), |
2 access_name char(32) unaligned, |
2 mode bit(36) aligned, |
2 extended_mode bit(36) aligned, |
2 status_code fixed bin(35); |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| where:
| access_name (Input)
| is the access name (in the form Person_id.Project_id.tag) that
| identifies the process to which the ACL entry applies.
| mode (Input)
| contains the modes for this access name. The first three bits
| correspond to the modes read, execute, and write. The
| remaining bits must be zero. The only allowed modes for DM
| files are null, read, and read/write. Execute is not a valid
| or meaningful mode for DM files. The include file
| access_modes_values.incl.pl1 defines mnemonics for these
| values:
| dcl (N_ACCESS init ("000"b),
| R_ACCESS init ("100"b),
| RW_ACCESS init ("101"b),
| bit(3) internal static
| options (constant);
| extended_mode (Input)
| should contain the value "0"b. (This field is for use with
| extended access and may only be used by the system).
| status_code (Output)
| is the storage system status code for this ACL entry only.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$adopt |
This entry point is only called by Data Management daemon through |
the dm_daemon_gate_. |
This entry is called when the daemon is adopting an abandoned |
transaction. The transaction may have been abandoned due to a |
process or system failure or due to a call to abandon the |
transaction by the transaction's owner. The effect of this call |
is to discard the list of pages that would be flushed by the file |
manager prior to a transaction commit. It is assumed that the |
adopted transaction will be rolled back. |
Usage |
dcl file_manager_$adopt entry (bit(36) aligned, fixed bin, |
fixed bin(35)); |
call file_manager_$adopt (txn_id, txn_idx, code); |
where: |
txn_id (Input) |
is the transaction identifier of the transaction to |
be adopted. Before this entry point is called, the |
per process control interval table pointer |
fm_data_$proc_txn_tbl_ptr should be pointing to a |
control interval table. This table is a list of |
control intervals that have been modified by the |
transaction, but not yet flushed. This entry clears |
that table. |
txn_idx (Input) |
is the corresponding index into the TDT for the |
transaction. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$allocate
Allocate allows applications to reserve disk space in large
chunks for better performance. It avoids the frequent updates to
the file map that occur by default if the control intervals are
allocated as needed by the put primitive. Allocate allocates
disk space for a set of consecutive control intervals of one
file. The set is specified by the number of the first control
interval, and the number of consecutive control intervals. It
attempts to allocate contiguous disk addresses to consecutive
control intervals, as much as possible. Allocate has a high
fixed overhead, so it should not be called for one control
interval at a time.
Usage
dcl file_manager_$allocate entry (bit (36) aligned, fixed
bin (27), fixed bin (27), fixed bin (35));
call file_manager_$allocate (oid, first_ci, n_ci, code);
where:
oid (Input)
is a file opening identifier.
first_ci (Input)
is the number of the first control interval.
n_ci (Input)
is the number of consecutive control intervals to
allocate.
code (Output)
is a standard status code. If it is
dm_error_$ci_already_allocated, the operation can
still be considered a success.
Notes
Allocate is currently not efficiently implemented, because the
only way to reserve a disk address for a page is to put something
in it. The semantics of allocate are designed to allow for
efficient implementation in a future.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$chname_file |
This entry point changes the entry name on a specified Data |
Management (DM) file. If a nonnull entry name is given for the |
oldname argument, the specified name is deleted from the DM file, |
if a nonnull entry name is given for the newname argument, the |
name is added to the DM file. Thus, if only an old name is |
specified, the effect is to delete a name; if only a new name is |
specified, the effect is to add a name; and if both a new and an |
old name is specified, the effect is to rename the DM file. |
Usage |
dcl file_manager_$chname_file entry (char(*), char(*), |
char(*), char(*), fixed bin(35)); |
call file_manager_$chname_file (dir_name, entryname, |
oldname, newname, code); |
where: |
dir_name (Input) |
is the pathname of the containing directory. |
entryname (Input) |
is the entryname of the DM file. |
oldname (Input) |
is the name to be deleted from the DM file. This |
argument can be null if newname is not null. |
newname (Input) |
is the name to be added to the entry. This name |
must not exist as the name of any other entry in the |
containing directory. If this argument is null, |
oldname must not be null and oldname cannot be the |
only name on the DM file. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$close
This entry "closes" a file in the current process. The file to
be closed is designated by its opening identifier.
Usage
dcl file_manager_$close entry (bit (36) aligned, fixed bin
(35));
call file_manager_$close (oid, code);
where:
oid (Input/Output)
is the file opening identifier of the file to be
closed. It is set to zero by this entry point in
order to indicate that it is no longer valid.
code (Output)
is a standard status code.
Notes
If the file has been opened more than once, closing it only
decrements the opening count. The description of the open
primitive says more about this.
There is no requirement for the caller to be in transaction mode
when closing a file, protected or not. Aborting a transaction
will not reopen it, even if it was closed by delete_close and the
deletion was rolled back.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$copy |
This entry point is called to copy a Data Management (DM) file. |
Usage |
dcl file_manager_$copy entry (ptr, fixed bin(35)); |
call file_manager_$copy (copy_options_ptr, code); |
where: |
copy_options_ptr (Input) |
is a pointer to the copy_options structure defined |
in the include file copy_options.incl.pl1 (described |
under notes below). |
code (Output) |
is the standard system status code. |
Notes |
The following is the form of the include file |
copy_options.incl.pl1: |
dcl 1 copy_options aligned based (copy_options|_ptr),
2 version char(8), |
2 caller_name char(32) unaligned, |
2 source_dir char(168) unaligned, |
2 source_name char(32) unaligned, |
2 target_dir char(168) unaligned, |
2 target_name char(32) unaligned, |
2 flags, |
3 no_name_dup bit(1) unaligned, |
3 raw bit(1) unaligned, |
3 force bit(1) unaligned, |
3 delete bit(1) unaligned, |
3 target_err_switch bit(1) unaligned, |
3 mbz bit(31) unaligned, |
2 copy_items like copy_flags; |
where: |
version (Input) |
is the current version of this structure. Currently |
COPY_OPTIONS_VERSION_1. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| caller_name (Input)
| is the name of the calling routine. This is required for the
| used of the duplicate name handler, nd_handler_.
| source_dir (Input)
| is the pathname of the directory containing the source DM
| file.
| source_name (Input)
| is the entryname of the source DM file.
| target_dir (Input)
| is the pathname of the directory of the target DM file.
| target_name (Input)
| is the entryname of target DM file.
| flags.no_name_dup (Input)
| If this flag is set, do not allow name duplication and do not
| call the name duplication handler if a name duplication
| occurs.
| flags.raw (Input)
| If this flag is set, use the standard hcs_ entries for copying
| the object. Do not use any special knowledge of the object
| type.
| flags.force (Input)
| if this flag is set, delete or force access to the target.
| flags.delete (Input)
| delete the original after copying.
| target_err_switch (Output)
| If this switch is set, then the error that occurred was with
| the target and not the source object.
| copy_items (Input)
| is a structure describing which attributes of the source
| should be copied to the target. (see the copy_flags.incl.pl1
| structure described at the suffix_info entry)
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$create
This entry creates a data management file. The caller specifies
its pathname and attributes, and must specify whether the file is
protected. See "Notes" below.
Usage
dcl file_manager_$create entry (char (*), char (*), ptr,
fixed bin (35));
call file_manager_$create (dir_path, entry_name,
file_create_info_ptr, code);
where:
dir_path (Input)
is the absolute pathname of a directory. The file
will be added to this directory.
entry_name (Input)
will be the name of the file.
file_create_info_ptr (Input)
points to the file_create_info structure. (See
notes below) If this pointer is null, an unprotected
file is created with the default attribute values.
code (Output)
is a standard status code.
Notes
The caller must have enough access to add an entry to the
directory. The file is created with read and write access for
the caller and Data_Management.Daemon.
In the current implementation, file attributes specified in the
file_create_info structure such as ring brackets and blocking
factor cannot be changed.
4 THE FILE_CREATE_INFO STRUCTURE
Following is the structure used to describe the attributes to
assign to a file being created. It is declared in
dm_file_create_info.incl.pl1.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
dcl 1 file_create_info aligned based (file_create_info_ptr),
2 version char (8) aligned,
2 ci_size_in_bytes fixed bin (35),
2 blocking_factor fixed bin,
2 flags unal,
3 protected bit (1) unal,
3 no_concurrency bit (1) unal,
3 no_rollback bit (1) unal,
3 mbz_1 bit (15) unal,
2 ring_brackets (2) fixed bin (3) unal,
2 mbz_3 bit (10) unal,
2 mbz_2 (30) fixed bin (71);
where:
version
must be set by the caller to FILE_CREATE_INFO_VERSION_2. This
permits upward compatible changes to this structure.
ci_size_in_bytes
is the control interval size. Currently the only size
available is 4096. If this item is zero, a default value is
used. Currently the default value is 4096.
blocking_factor
tells the file manager how to allocate disk storage. In the
current implementation this will be interpreted as the number
of control intervals to put in each segment, and only 64 and
255 will be allowed. If this item is zero, a default value is
used. The current default value is 255.
flags.protected
determines whether the file is protected from transaction
failure and from concurrent access by other processes. If the
protected bit is on, get, put, and allocate operations are
permitted only in transaction mode. Create and delete
operations are protected regardless of whether the process is
in a transaction. If this bit is off, the file is
unprotected, which means that the file and its contents may be
damaged by concurrent access or transaction failure. An
unprotected file may be accessed within or without a
transaction. Accessing a protected file is substantially more
expensive than accessing an unprotected file. The default is
to provide protection.
flags.no_concurrency
turns off protection against concurrent access by other
processes. Concurrency protection is implemented by locking
each control interval that is accessed. The get operation
_____________ _____________
file_manager_ file_manager_
_____________ _____________
locks in share mode. All other operations lock in exclusive
mode. Create and delete lock the entire file in exclusive
mode. Locking is expensive. This bit turns it off if it is
not needed. If protection is off, this bit is ignored. The
default is to provide concurrent access protection.
flags.no_rollback
turns off protection against transaction failure. Protection
against transaction failure is implemented by journaling a
before image of each modification. When a transaction fails,
its modifications are undone by restoring these before images.
Journaling is expensive. This bit turns it off if it is not
needed. If protection is off, this bit is ignored. The
default is to provide protection from transaction failure.
ring_brackets
are the extended ring brackets of the file. They specify the
range of rings from which the file may be accessed. The first
is the write bracket. It's value cannot be less than the Data
Management ring (loosely, the ring of execution of the
file_manager_) or the validation level of the creating
process. The second is the read bracket. It's value cannot
be less than the write bracket. The default for both ring
brackets is the validation level of the calling process.
mbz_1, mbz_2, mbz_3
must be initialized to zero by the caller. This is so that
upward compatible changes will be able to assume that existing
programs put zeros in these areas.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$create_open
Calling this entry point is like calling create and open, but it
is more efficient. If the file already exists, it will be opened
and code_o will be dm_error_$file_already_exists. If the file
already exists and is already open, the opening identifier will
be returned and code_o will be dm_error_$file_already_open.
Usage
dcl file_manager_$create_open entry (char (*), char (*),
ptr, bit (36) aligned, fixed bin (35));
call file_manager_$create_open (dir_path, entry_name,
file_create_info_ptr, oid, code);
where:
dir_path (Input)
is the absolute pathname of a directory. The file
will be added to this directory.
entry_name (Input)
will be the name of the file.
file_create_info_ptr (Input)
is described under the create entry point.
oid (Output)
is the opening identifier assigned to the file. If
it is not zero, the oid is valid and can be used,
regardless of the value of code_o. If the
transaction aborts and the file is deleted, it still
needs to be closed, since openings are not undone by
rollback.
code (Output)
is a standard status code. If it is
dm_error_$file_already_exists or
dm_error_$file_already_open, the operation is
considered successful and oid_o is usable.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$delentry_file |
This entry deletes a file specified by its pathname. The user |
must have the proper access to delete an entry in the containing |
directory and have write access to the file itself. |
The deletion of the file is protected. If the deletion is |
requested outside of a transaction, a transaction is begun, and |
committed after the deletion. |
Usage |
dcl file_manager_$delentry_file entry (char(*), char(*), |
fixed bin(35)); |
call file_manager_$delentry_file (dir_name, entryname, |
code); |
where: |
dir_name (Input) |
is the name of the directory containing the Data |
Management (DM) file to be deleted. |
entryname (Input) |
is the entryname of the DM file. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$delete_acl_entries
| This entry point deletes specified entries from an access control
| list (ACL) for a data management (DM) file.
| Usage
| dcl file_manager_$delete_acl_entries entry (char(*),
| char(*), ptr, fixed bin, fixed bin(35));
| call file_manager_$delete_acl_entries (dir_name, entryname,
| acl_ptr, acl_count, code);
| where:
| dir_name (Input)
| is the pathname of the directory containing the Data
| Management (DM) file.
| entryname (Input)
| is the entryname of the DM file.
| acl_ptr (Input)
| points to a user-supplied delete_acl structure (see
| "notes" below).
| acl_count (Input)
| is the number of ACL entries in the delete_acl
| structure (see "notes" below).
| code (Output)
| is the standard system status code.
| Notes
| The delete_acl structure should be declared in the following way:
| dcl 1 delete_acl (acl_count) aligned based (acl_ptr),
| 2 access_name char(32) unaligned,
| 2 status_code fixed bin(35);
| where:
| access_name (Input)
| is the access name (in the form of Person_id.Project_id.tag)
| that identifies the ACL entry to be deleted.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
status_code (Output) |
is the storage system status code for this entry only. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$delete_close
Calling this entry point is like calling delete and then close,
but it is more efficient. It is for deleting a file that is
already open.
Usage
dcl file_manager_$delete_close entry (bit (36) aligned,
fixed bin (35));
call file_manager_$delete_close (oid, code);
where:
oid (Input/Output)
is the file opening identifier of the file to be
deleted and closed. It is set to zero by this entry
point in order to indicate that it is no longer
valid. The file remains closed even if the
transaction aborts and the deletion does not remain
in effect.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$end_of_crash_recovery
This entry is called by dm_recovery as an inner ring entry point.
This entry must be called after calls to
file_manager_$open_by_uid_after_crash have ceased. It terminates
the old uid/pathname table.
Usage
dcl file_manager_$end_of_crash_recovery entry (fixed bin
(35));
call file_manager_$end_of_crash_recovery (code);
where:
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$find_old_uid_pn_table
This entry is a priviledged inner ring entry point. The entry
must be called to prepare the file manager for calls to
file_manager_$open_by_uid_after_crash. It initiates the old
uid/pathname table that it finds in the old bootload directory,
the pathname of which is provided by the caller.
Usage
dcl file_manager_$find_old_uid_pn_table entry (char (*),
fixed bin (35));
call file_manager_$find_old_uid_pn_table (old_boot_dir_path,
code);
where:
old_boot_dir_path (Input)
is the absolute pathname of the old bootload
directory.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$flush_consecutive_ci
This entry point provides a service needed by the before journal
manager, in response to a request it gets at commit time from the
transaction manager, to flush the before images produced by the
committing transaction. It is not intended to be used on
protected files, because it makes no provision for pages that may
be held in memory awaiting before journal writes.
It flushes a set of consecutive control intervals. The caller
specifies the number of the first control interval to be flushed,
and the number of control intervals to be flushed, starting at
the first one. It does not return until all control intervals
have been written to disk.
Usage
dcl file_manager_$flush_consecutive_ci entry (bit (36)
aligned, fixed bin (27), fixed bin (27), fixed bin
(35));
call file_manager_$flush_consecutive_ci (oid, first_ci,
n_ci, code);
where:
oid (Input)
is a file opening identifier.
first_ci (Input)
is the control interval number of the first control
interval to be flushed.
n_ci (Input)
is the number of control intervals to be flushed.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$flush_modified_ci
This entry provides a service needed by the transaction manager
only. It writes to disk all modified control intervals of
protected files for the specified transaction that have not been
written to disk yet. It does not return to its caller until all
modified control intervals have been flushed to disk.
The put, allocate, and free primitives maintain, for each
transaction, a list of all control intervals that have been
modified by the transaction and that are part of a protected
file. It is legitimate for a transaction to modify both
protected and unprotected files, but only control intervals of
protected files are entered in the list and flushed by this
primitive.
Usage
dcl file_manager_$flush_modified_ci entry (bit (36) aligned,
fixed bin, fixed bin (35));
call file_manager_$flush_modified_ci (txn_id, txn_idx,
code);
where:
txn_id (Input)
is a transaction identifier.
txn_idx (Input)
is the corresponding transaction index.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$free
This entry frees disk space allocated to control intervals. The
set of consecutive control intervals is specified by the number
of the first control interval and the number of consecutive
control intervals starting at the first one. After the disk
space for a control interval has been freed, its content is
effectively zero. This operation is has a high fixed overhead,
so it should not be called for one control interval at a time.
If any or all of the control intervals are already free, code_o
is set to dm_error_$ci_already_free. The operation is,
nevertheless, successful.
Usage
dcl file_manager_$free entry (bit (36) aligned, fixed bin
(27), fixed bin (27), fixed bin (35));
call file_manager_$free (oid, first_ci, n_ci, code);
where:
oid (Input)
is a file opening identifier.
first_ci (Input)
is the control interval number of the first control
interval of the set whose physical space is to be
freed.
n_ci (Input)
is the number of consecutive control intervals whose
physical space is to be freed.
code (Output)
is a standard status code. If it is
dm_error_$ci_already_free, the operation can still
be considered a success.
Notes
The user must have write access to the file.
If the file is protected, the caller must be in transaction mode
and the free operation is done under the auspices of the
integrity services. If the transaction aborts, the control
intervals are reallocated and their contents restored.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get
This entry reads data from a control interval. The caller may
specify one or several parts. Each part is described by its byte
offset relative to the beginning of the addressable portion of
the control interval and its length in bytes. Each part has a
pointer to a buffer provided by the caller.
If the control interval does not exist, the buffers provided by
the caller are filled with zeros and code_o is set to zero.
Usage
dcl file_manager_$get entry (bit (36) aligned, fixed bin
(27), ptr, fixed bin (35));
call file_manager_$get (oid, ci_num, ci_parts_ptr, code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr (Input)
points to the structure described under "ci_parts
structure" below.
code (Output)
is a standard status code.
Notes
If the file is protected, the process must be in a transaction,
and unless no_concurrency is specified, get locks the control
interval in share mode. It is kept locked until the end of the
transaction. This assures that no other transaction will put
anything into the control interval, free it, or delete the file
during the current transaction. If the control interval is
locked in exclusive mode by another transaction, get will wait
until it finishes. If waiting is pointless because the current
transaction is deadlocked with another transaction, the
transaction_deadlock condition is signaled (see
txn_deadlock_info.incl.pl1).
The calling process must have read access in order to do a get.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
ci_parts structure
The structure is in dm_ci_parts.incl.pl1. The constants are in
dm_ci_lengths.incl.pl1.
dcl 1 ci_parts aligned based (ci_parts_ptr),
2 number_of_parts fixed bin,
2 part (cip_number_of_parts
refer (ci_parts.number_of_parts)),
3 offset_in_bytes fixed bin,
3 length_in_bytes fixed bin,
3 local_ptr ptr;
dcl ci_parts_ptr ptr;
dcl cip_number_of_parts fixed bin;
dcl CI_ADDRESSABLE_LENGTH fixed bin
init (4072) static options (constant);
dcl CI_0_ADDRESSABLE_LENGTH fixed bin
init (3176) static options (constant);
where:
number_of_parts
is the number of parts. Zero is legal and there is currently
no limit on the number of parts.
offset_in_bytes
is the offset of the part within the addressable portion of
the control interval. It is the zero relative index of the
first byte of the part. It is the number of bytes that are to
be skipped, starting at the beginning of the addressable
portion.
The addressable portion of a control interval begins with the
first byte after the four word header and ends with the last
byte before the two word trailer. The only exception is
control interval zero. It has a smaller addressable portion,
because the file attributes are stored in it.
The length of the addressable portion is 4072 bytes. Control
interval zero has 3176 bytes.
length_in_bytes
is the number of bytes in the part. If it is zero, the part
is ignored.
local_ptr
_____________ _____________
file_manager_ file_manager_
_____________ _____________
is a pointer to the buffer provided by the caller for the
part.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get_ci_header
This entry reads the 4 word control interval header. Its
structure is given below. It tells the unique identifier of a
data management file, whether a control interval is allocated,
and the time it was last modified.
Protection and access are the same as the get entry.
If the control interval does not exist, this entry returns the
header that it would have had, with zero in the time_modified
field and code_o set to zero. It does not create the control
interval.
Usage
dcl file_manager_$get_ci_header entry (bit (36) aligned,
fixed bin (27), 1 like ci_header aligned, fixed bin
(35));
call file_manager_$get_ci_header (oid, ci_num, ci_header,
code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_header (Input/Output)
is the structure described under "ci_header
structure" below.
code (Output)
is a standard status code.
ci_header structure
The ci_header structure is in dm_ci_header.incl.pl1.
dcl 1 ci_header_o like ci_header aligned;
dcl ci_header_ptr ptr;
dcl 1 ci_header aligned based (ci_header_ptr),
2 stamp,
3 version bit (9) unal,
_____________ _____________
file_manager_ file_manager_
_____________ _____________
3 bj_idx fixed bin (9) uns unal,
3 time_modified fixed bin (53) unal,
2 id,
3 uid bit (36) unal,
3 size_code
4 exponent fixed bin (6) uns,
4 addon fixed bin (3) uns,
3 num fixed bin (27) uns unal;
dcl CI_HEADER_STAMP_VERSION_1 bit (9) aligned
static options (constant) init ("641"b3);
where:
version
must be set to CI_HEADER_STAMP_VERSION_1 by the caller.
bj_idx
is used to synchronize control interval writes with before
journal writes.
time_modified
is the Multics clock time when this control interval was last
modified. If the control interval does not exist, this item
is zero.
uid
is the unique identifier of the data management file. It is
not the Multics file system uid.
size_code
gives the physical size of the control interval which includes
the header and trailer. The size in bytes = (64 + 8 * addon)
* 2**exponent.
num
is the control interval number. The number of the first
control interval is zero.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get_ci_ptr
This entry returns a pointer to the addressable portion of a
control interval. Pointers to control intervals should be used
only in well defined and contained situations to enhance the
performance of accessing data in a control interval for retrieval
purposes. This entry is helpful when it is known beforehand that
several pieces of data are to be read from the same control
interval, but they cannot be read by specifying several parts to
the get entry (e.g., the offset of one is dependent on the value
of another). Unlike other entries which get data, it is not
valid to get a control interval pointer to a control interval
that is not allocated.
Usage
dcl file_manager_$get_ci_ptr entry (bit (36) aligned, fixed
bin (27), ptr, fixed bin (35));
call file_manager_$get_ci_ptr (oid, ci_num, ci_ptr, code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_ptr (Input)
points to the addressable portion of the control
interval. The addressable portion begins
immediately after the control interval header. A
null value is returned for this pointer if there is
a error and the returned code is not zero.
code (Output)
is a standard status code. One possible value is:
dm_error_$ci_not_allocated - The specified control
interval has not been allocated. ci_ptr_o is
set to null.
Notes
In order to make it possible to look at control intervals via a
pointer, the create primitive sets the ring brackets on file
components to
<DM-ring>,<validation-level>,<validation-level>.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
If the file is protected, the process must be in a transaction,
and unless no_concurrency is specified, get_ci_ptr locks the
control interval in share mode. It is kept locked until the end
of the transaction. This assures that no other transaction will
put anything into the control interval, free it, or delete the
file during the current transaction. If the control interval is
locked in exclusive mode by another transaction, get_ci_ptr will
wait until it finishes. If waiting is pointless because the
current transaction is deadlocked with another transaction, an
appropriate status code is returned.
If the control interval does not exist, an error code of value
dm_error_$ci_not_allocated. The calling process must have read
access in order to do a get_ci_ptr.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get_exclusive
This entry is just like the get entry point except that it locks
the control interval exclusively. It prevents other transactions
from even obtaining the share lock necessary to do a get. It is
for application that usually do a put into the same control
interval. Since it reduces concurrency, it should not be used
unless it can be established that it gains more than it loses.
Usage
dcl file_manager_$get_exclusive entry (bit (36) aligned,
fixed bin (27), ptr, fixed bin (35));
call file_manager_$get_exclusive (oid, ci_num, ci_parts_ptr,
code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr_ (Input)
points to a ci_parts structure which is described
under the get entry.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$get_max_length
| This entry point, given a directory name and a entry name,
| returns the maximum length in words of a Data Management (DM)
| file. This entry point is currently not implemented in the Data
| Management system.
| Usage
| dcl file_manager_$get_max_length entry (char(*), char(*),
| fixed bin(19), fixed bin(35));
| call file_manager_$get_max_length (dir_name, entryname,
| max_length, code);
| where:
| dir_name (Input)
| is the pathname of the containing directory.
| entryname (Input)
| is the entry name of the DM file.
| max_length (Output)
| is the maximum length in words of the DM file.
| Notes
| The user must have status permission on the directory containing
| the segment or nonnull access to the segment.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get_ring_brackets |
This entry point returns the extended ring brackets of a Data |
Management (DM) file. |
Usage |
dcl file_manager_$get_ring_brackets entry (char (*), char |
(*), (2) fixed bin (3), fixed bin (35)); |
call file_manager_$get_ring_brackets (dir_name, entry_name, |
ring_brackets, code); |
where: |
dir_name (Input) |
is the pathname of the containing directory. |
entryname (Input) |
is the entry name of the DM file. |
ring_brackets (Output) |
are the ring brackets of the DM file. This is a two |
element array, allocated by the caller, with the |
first bracket being the file's write bracket and the |
second being the file's read bracket. |
code (Output) |
is the standard status code. |
Notes |
The user must have status permission on the containing directory |
or nonnull access to the file. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$get_stream
| This entry point will return a specified number of bytes from a
| Data Management (DM) file given an opening id, a file offset, and
| a buffer in which to place the bytes. This entry treats the DM
| file as a stream of bytes made up of the concatenation of the
| addressable portion of all control intervals in the DM file.
| Usage
| dcl file_manager_$get_stream entry (bit(36) aligned, fixed
| bin(48), ptr, fixed bin(21));
| call file_manager_$get_stream (oid, file_offset_in_bytes,
| buf_ptr, buf_length_in_bytes);
| where:
| oid (Input)
| is the opening id of the DM file to be read from.
| file_offset_in_bytes (Input)
| is the offset given in bytes from the beginning of
| the logical address space of the DM file given in
| bytes with an offset of zero representing the
| beginning of the file.
| buf_ptr (Input)
| is a pointer to a buffer where the bytes read from
| the DM file may be placed.
| buf_length_in_bytes (Input)
| is the number of bytes that are to be read from the
| DM file.
Notes
If the DM file is protected, the process must be in a
transaction, and unless concurrency is specified, get_stream
locks in share mode the control intervals in which the specified
stream of bytes resides.
The calling process must have read access to the DM file in order
to do a get_stream.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$get_switch |
This entry point, given a directory name, an entry name, and a |
switch name, returns the value, "0"b or "1"b, of that switch. |
Currently the only valid switch name is "safety". |
Usage |
dcl file_manager_$get_switch entry (char(*), char(*), |
char(*), bit(1), fixed bin(35)); |
call file_manager_$get_switch (dir_name, entryname, |
switch_name, switch_value, code); |
where: |
dir_name (Input) |
is the pathname of the containing directory. |
entryname (Input) |
is the entry name of the DM file. |
switch_name (Input) |
is the name of the switch. |
switch_value (Output) |
is the value of the specified switch. |
code (Output) |
is the standard system status code. |
Notes |
The calling process must have read access to the DM file. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$get_user_access_modes
| This entry point returns the effective access mode and extended
| access mode of a user to a Data Management (DM) file given a
| directory name, an entry name, a user_id, and the validation
| level (ring number) of the user. (For a description of effective
| access see "Effective Access" in the Reference Manual.)
| Usage
| dcl file_manager_$get_user_access_modes entry (char(*),
| char(*), char(*), fixed bin, bit(36) aligned, bit(36)
| aligned, fixed bin(35));
| call file_manager_$get_user_access_modes (dir_name,
| entryname, user_id, ring, modes, ex_modes, code);
| where:
| dir_name (Input)
| is the pathname of the containing directory.
| entryname (Input)
| is the entry name of the DM file.
| user_id (Input)
| is the access name of the user (in the form
| Person_id.Project_id_.tag). The user id is limited
| to 32 characters. If null, the access name of the
| calling process is used.
| ring (Input)
| is the validation level that is to be used in
| computing effective access. It must be a value
| between 0 and 7 inclusive, or -1. If the ring value
| is -1, a default value of the validation level of
| the calling process is used. This default should be
| used in all cases except those in which a different
| ring's access is explicitly required.
| mode (Output)
| is the effective access mode of the user to the DM
| file (see "Notes" below).
| ex_mode (Output)
| is the extended access mode of the user to the DM
| file.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
code (Output) |
is the standard system status code. |
Notes |
The user must have status permission on the containing directory, |
unless the access name supplied is that of the calling process or |
null. |
The include file access_modes_values.incl.pl1 defines mnemonics |
for the different values of mode (see "Notes" at |
add_acl_entries). |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$list_acl
| This entry point returns either the entire access control list
| (ACL) of a Data Management (DM) file or it returns the access
| modes of specified ACL entries.
| Usage
| dcl file_manager_$list_acl entry (char(*), char(*), ptr,
| ptr, ptr, fixed bin, fixed bin(35));
| call file_manager_$list_acl (dir_name, entryname, area_ptr,
| area_ret_ptr, acl_ptr, acl_count, code);
| where:
| dir_name (Input)
| is the pathname of the containing directory.
| entryname (Input)
| is the entryname of the segment.
| area_ptr (Input)
| is a pointer to an area where the list of ACL
| entries is to be allocated. If this pointer is
| null, then the modes of the ACL entries specified in
| the structure pointed to by acl_ptr will be filled
| in instead.
| area_ret_ptr (Output)
| points to the start of the allocated list of ACL
| entries.
| acl_ptr (Input)
| If area pointer is null, then acl_ptr should point
| to an ACL structure, segment_acl, (described at the
| add_acl_entries entry point above) into which mode
| information is placed for the access names specified
| in that same structure.
| acl_count (Input/Output)
| is the number of entries supplied in the ACL
| structure identified by acl_ptr when area_ptr is
| null, or if area_ptr is not null, then acl_count is
| the number of entries returned in the ACL structure
| allocated in the area that area_ptr points to.
| code (Output)
| is the standard system status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$list_switches |
This entry point returns the names of nonstandard switches on |
Data Management (DM) files. |
Usage |
dcl file_manager_$list_switches entry (ptr, ptr); |
call file_manager_$list_switches (area_ptr, |
switch_list_ptr); |
where: |
area_ptr (Input) |
is a pointer to an area that the entry point may |
allocate the switch list in. |
switch_list_ptr (Output) |
is a pointer to the beginning of the switch list |
allocated in the user area provided. The |
switch_list structure is defined in the include file |
suffix_info.incl.pl1 (see "notes" below for a |
description of the switch_list structure). |
Notes |
The switch_list structure has the following form: |
dcl 1 switch_list aligned based (switch_list_ptr), |
2 version char(8), |
2 switch_count fixed bin, |
2 switch_name_count fixed bin, |
2 switches (alloc_switch_count refer |
(switch_list.switch_count)), |
3 name_index fixed bin, |
3 name_count fixed bin, |
3 default_value bit (1) aligned, |
3 mbz1 bit (36) aligned, |
2 names (alloc_switch_name_count refer |
(switch_list.switch_name_count)) |
char (32); |
where: |
version |
is the version string of his structure. Currently |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| SWITCH_LIST_VERSION_1.
| switch_count
| is the number of switches in this structure.
| switch_name_count
| is the number of switch names in this structure. There can be
| more than one name for each switch.
| switches.name_index
| is the index into the names array of the first name for this
| switch.
| switches.name_count
| is the count of the number of names in the name array for this
| switch.
| switches.default_value
| is the default switch setting for this switch.
| names
| is an array of names of switches that are referenced in the
| switches array.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$lock_advice
This entry permits applications to give the file manager advice
about locking granularity. For example, if the application knows
that it is going to modify every control interval in a file, it
can tell the file manager to lock the entire file and save the
overhead of locking individual control intervals.
Usage
dcl file_manager_$lock_advice entry (bit (36) aligned, fixed
bin, fixed bin (35));
call file_manager_$lock_advice (oid, lock_mode, code);
where:
oid (Input)
is a file opening identifier.
lock_mode (Input)
is the finest and weakest lock mode to use on this
file for the remainder of the opening. It must be
one of the five following modes: 4 (LOCK_MODE_IS),
5 (LOCK_MODE_IX), 6 (LOCK_MODE_SIX), 2
(LOCK_MODE_S), or 3 (LOCK_MODE_X) which are declared
in dm_lock_modes.incl.pl1.
code (Output)
is a standard status code.
Notes
Lock advice never abridges protection against concurrent file
access by other processes. If no lock advice is given, file
manager uses the weakest lock necessary to provide concurrency
protection, and the finest granularity available, which is the
control interval. Lock advice always causes file manager to use
a stronger lock or coarser granularity than absolutely necessary.
This reduces concurrency in order to reduce locking overhead.
Lock advice applies to protected files unless the no_concurrency
attribute is present. It can be given to any open file,
regardless of whether a transaction is in progress. It is an
attribute of the opening and not of the file. It is used the
first time the file is referenced in each transaction. It tells
the file manager what kind of a global file lock to acquire. If
the Lock advice is given after the first time the file is
_____________ _____________
file_manager_ file_manager_
_____________ _____________
referenced, it probably won't be used until the next transaction.
The lock advice is retained until it is changed, or the file is
closed.
The advice concerns the type of lock to use at the file level.
The only way to control the type of lock used on a control
interval is to call get_exclusive instead of get. If no advice
is given, IS (intention shared) is presumed. IS is strong enough
for get and get_ci_header which lock control intervals in S
(shared) mode. Put, allocate, and free require that the file
lock be upgraded to the stronger IX (intention exclusive) mode,
because they lock control intervals in X (exclusive) mode.
Create and delete lock the file in X mode, regardless. If advice
is given, then all operations lock the file in the advised mode
unless it is too weak for the operation. The SIX (shared and
intention exclusive) mode means only lock the control intervals
that are modified. SIX saves the overhead of locking individual
control intervals for get operations because it prevents other
transactions from getting anything but an IS lock on the file.
A full explanation of locking is in MTB-514, "Data Management:
Concurrency Management - Overview".
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$open
This entry makes a data management file accessible within a
process. The file is specified by its pathname. The file
manager assigns an opening identifier to the file in the current
process. It is used to designate the file in subsequent calls to
the file manager.
Usage
dcl file_manager_$open entry (char (*), char (*), bit (36)
aligned, fixed bin (35));
call file_manager_$open (dir_path, entry_name, oid, code);
where:
dir_path (Input)
is the absolute pathname of the directory which
contains the file.
entry_name (Input)
is the entry name of the file.
oid (Output)
is the file opening identifier assigned to the file
and returned to the caller. If it is not zero, it
is usable, regardless of code_o.
code (Output)
is a standard status code. If it is
dm_error_$file_already_open, the operation is
considered successful and oid_o is usable.
Notes
If the file was already opened in the current process, the open
primitive does not assign a new opening identifier, instead it
returns the opening identifier that was already assigned and sets
code_o to dm_error_$file_already_open. The file manager keeps
track of the number of opens and closes. The opening identifier
remains valid as long as there have been more opens than closes.
If all subsystems within a process close a file the same number
of times they opens it, they will not invalidate each others
openings.
There is no requirement for the process to be in a transaction
when opening a file, protected or not. Aborting a transaction
_____________ _____________
file_manager_ file_manager_
_____________ _____________
has no effect on file openings, even if create_open was called
and the create is rolled back. Attempts to use such an opening
will result in dm_error_$file_doesnt_exist. The same thing
happens if a file is opened and then deleted. Close is the only
legal operation on a file which has been deleted.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$open_by_uid
This entry point serves the before journal manager, which keeps
the file unique identifier in each before image. When a
transaction is rolled back by another process, before journal
manager converts the unique identifier into an opening identifier
by calling this entry point.
File manager maintains a conversion table in which it keeps the
unique identifiers and pathnames of all protected files that are
open in any process. This entry point uses that table to get the
pathname of the file and open it. The opening is ordinary in
every other way.
Usage
dcl file_manager_$open_by_uid entry (bit (36) aligned, bit
(36) aligned, fixed bin (35));
call file_manager_$open_by_uid (uid, oid, code);
where:
uid (Input)
is the unique identifier of the file to be opened.
oid (Output)
is the file opening identifier assigned to the file
and returned to the caller. If it is not zero, it
is usable, regardless of code_o.
code (Output)
is a standard status code. If it is
dm_error_$file_already_open, the operation is
considered successful and oid_o is usable.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$open_by_uid_after_crash
This entry is a priviledged inner ring entry point. The entry
works like open_by_uid, except it uses the uid/pathname table
from the previous bootload and does not lock it. The opening
produced is standard in every way. Before this entry can be
called, file_manager_$find_old_uid_pn_table must be called so
that file manager can initiate the old uid/pathname table. After
crash recovery is finished, file_manager_$end_of_crash_recovery
should be called so that file manager can terminate the old
uid/pathname table prior to its impending deletion with the old
bootload directory.
Usage
dcl file_manager_$open_by_uid_after_crash entry (bit (36)
aligned, bit (36) aligned, fixed bin (35));
call file_manager_$open_by_uid_after_crash (uid, oid, code);
where:
uid (Input)
is the unique identifier of the file to be opened.
oid (Output)
is the file opening identifier assigned to the file
and returned to the caller. If it is not zero, it
is usable, regardless of code_o.
code (Output)
is a standard status code. If it is
dm_error_$file_already_open, the operation is
considered successful and oid_o is usable.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$per_system_init
This entry is called during per system initialization. It
creates and initializes file manager's per system tables.
Usage
dcl file_manager_$per_system_init entry (fixed bin (35));
call file_manager_$per_system_init (code);
where:
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$post_commit
This entry is called by the transaction manager after a
transaction has committed. The File Manager keeps a list of post
commit actions associated with each transaction.
Post commit actions close protected files whose closing was
postponed until the end of the transaction, delete protected
files whose deletion was postponed, and remove shriek names that
were used to create protected files during the transaction.
Usage
dcl file_manager_$post_commit entry (bit (36) aligned, fixed
bin, fixed bin (35));
call file_manager_$post_commit (txn_id, txn_idx, code);
where:
txn_id (Input)
is a transaction identifier.
txn_idx (Input)
is the corresponding transaction index.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$prepare_to_copy |
This entry point is called prior to copying a Data Management |
(DM) file. It locks the file, gets its attributes, and |
determines is length. |
Usage |
dcl file_manager_$prepare_to_copy entry (bit(36) aligned, |
ptr, fixed bin(27), fixed bin(35)); |
call file_manager_$prepare_to_copy (oid, |
file_create_info_ptr, last_ci_num, code); |
where: |
oid (Input) |
is the opening id of the DM file. |
file_create_info_ptr (Input) |
is a pointer to a file_create_info structure that |
the file attributes are to be placed in. This |
structure may in turn be used to create a new DM |
file to copy the old DM file into. The |
file_create_info structure is defined in the |
dm_fm_create_info.incl.pl1 include file. (see |
"notes" under "create" for a description of this |
include file). |
last_ci_num (Output) |
is the number of the last control interval in the DM |
file. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$put
This entry writes data into a control interval. The caller may
specify one or several parts of the control interval to be
written. The parts are described under the get entry point.
If the control interval does not exist, it is automatically
allocated and the content of its addressable portion is
initialized to zero.
Usage
dcl file_manager_$put entry (bit (36) aligned, fixed bin
(27), ptr, fixed bin (35));
call file_manager_$put (oid, ci_num, ci_parts_ptr, code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr (Input)
points to the structure described under the get
primitive.
code (Output)
is a standard status code.
Notes
If the file is protected, the process must be in a transaction,
and unless no_concurrency is specified, put locks the control
interval in exclusive mode. It is kept locked until the end of
the transaction. This assures that no other transaction will put
anything into the control interval, get anything from it, free
it, or delete the file during the current transaction. If the
control interval is locked by another transaction, put will wait
until it finishes. If waiting is pointless because the current
transaction is deadlocked with another transaction, an
appropriate status code is returned.
Unless the file is unprotected or has the no_rollback attribute,
put journals a before image of the data already in the control
interval before actually modifying it. If the transaction should
_____________ _____________
file_manager_ file_manager_
_____________ _____________
abort, the before journal manager will undo its modifications by
restoring the before images.
The modified control interval can not be written to disk until
its before image is on disk, because there must be enough
information on disk to roll back the transaction even if main
memory fails. If the modified control interval were written
first and the system failed before the transaction finished and
the content of main memory could not be flushed to disk, the
modification could not be undone and rollback of the transaction
would be incomplete. The data management system holds modified
control intervals in main memory until the associated before
images are written to disk. The Multics clock value in the
control interval header is used for this purpose. More details
are in MTB-564, "Phasing Page Control and Before Journal".
The put request is rejected if:
- The user does not have write permission on the file.
- The file is protected but the process is not in a
transaction. in any file (ie. "never_write" mode).
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$put_journal
| This entry point writes data into a control interval of a before
| journal. This entry operates exactly as the entry put does, but
| this entry is only called by the before journal and is maintained
| separately so that the Before Journal manager's use of puts may
| be monitored. The caller may specify one or several parts of the
| control interval to be written. The parts structure is described
| under the get entry point.
| Usage
| dcl file_manager_$put_journal entry (bit(36) aligned, fixed
| bin(27), ptr, fixed bin(35));
| call file_manager_$put_journal (oid, ci_num, ci_parts_ptr,
| code);
| where:
| oid (Input)
| is the opening id of the Data Management (DM) file.
| ci_num (Input)
| is the control interval number.
| ci_parts_ptr (Input)
| is a pointer to a ci_parts structure (described
| under the get entry point).
| code (Output)
| is a standard system status code.
| Notes
| See the notes at the put entry point.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$put_stream |
This entry point will write a number of bytes into a DM file at a |
given offset into the logical address space. This entry treats |
the DM file as a stream of bytes made up of the concatenation of |
the addressable portion of all control intervals in the DM file. |
Usage |
dcl file_manager_$put_stream entry (bit(36) aligned, fixed |
bin(48), ptr, fixed bin(21), fixed bin(35)); |
call file_manager_$put_stream (oid, file_offset_in_bytes, |
buf_ptr, buf_length_in_bytes, code); |
where: |
oid (Input) |
is the opening id of the of the DM file. |
file_offset_in_bytes (Input) |
is the offset in bytes into the logical address |
space of the DM file where the supplied bytes will |
be placed. |
buf_ptr (Input) |
is a pointer to the buffer containing the bytes to |
be written to the DM file. |
buf_length_in_bytes (Input) |
is the number of bytes to be written into the DM |
file from the buffer. |
code (Input) |
is the standard system status code. |
Notes |
If the DM file is protected, the process must be in a |
transaction, and unless concurrency is specified, put_stream |
locks the control intervals in which the specified stream of |
bytes resides. |
The calling process must have write access to the DM file in |
order to do a put_stream operation |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$raw_get
This entry is like the get entry, except that it treats the file
as if it were unprotected. It does not require that the process
be in a transaction.
Usage
dcl file_manager_$raw_get entry (bit (36) aligned, fixed bin
(27), ptr, fixed bin (35));
call file_manager_$raw_get (oid, ci_num, ci_parts_ptr,
code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr (Input)
points to a ci_parts structure which is described
under the get entry.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$raw_put
This entry point is like put, except that it treats the file as
if it were unprotected. Furthermore, the time_modified stamp in
the control interval header is not updated. It is intended for
applications that need to update protected files in an
unprotected manner. It does not require that the process be in a
transaction.
Usage
dcl file_manager_$raw_put entry (bit (36) aligned, fixed bin
(27), ptr, fixed bin (35));
call file_manager_$raw_put (oid, ci_num, ci_parts_ptr,
code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr (Input)
points to the structure described under the get
primitive.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$replace_acl
| This entry point replaces an entire access control list (ACL) for
| a Data Management (DM) file with a user-supplied ACL, and can
| optionally add an entry for *.SysDaemon.* with mode rw to the new
| ACL. The segment_acl structure described at the add_acl_entries
| entry point is used by this entry.
| Usage
| dcl file_manager_$replace_acl entry (dir_name, entryname,
| acl_ptr, acl_count, no_sysdaemon, code);
| call file_manager_$replace_acl (char(*), char(*), ptr, fixed
| bin, bit(1), fixed bin(35));
| where:
| dir_name (Input)
| is the pathname of the directory containing the DM
| file.
| entryname (Input)
| is the entry name of the DM file.
| acl_ptr (Input)
| is a pointer to the user-supplied segment_acl
| structure that is to replace the current ACL.
| acl_count (Input)
| is the number of ACL entries in the segment_acl
| structure.
| no_sysdaemon (Input)
| is a switch that indicates whether an rw
| *.SysDaemon.* entry is to be put on the ACL of the
| DM file after the existing ACL has been deleted and
| before the user supplied ACL is added.
| code (Output)
| is the standard system status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$set_ring_brackets |
This entry point, given the pathname of a Data Management (DM) |
file, sets the file's ring brackets. This entry is unimplemented |
in the current Data Management system. |
Usage |
dcl file_manager_$set_ring_brackets entry (char (*), char |
(*), (2) fixed bin (3), fixed bin (35)); |
call file_manager_$set_ring_brackets (dir_name, entry_name, |
ring_brackets, code); |
where: |
dir_name (Input) |
is the pathname of the containing directory. |
entryname (Input) |
is the entry name of the DM file. |
ring_brackets (Input) |
are the ring brackets of the DM file. This is a two |
element array with the first bracket being the |
file's write bracket and the second being the file's |
read bracket. |
code (Output) |
is the standard status code. |
Notes |
The user must have modify permission on the containing directory. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$set_switch
| This entry point sets the value of a named switch associated with
| a given Data Management (DM) file.
| Usage
| dcl file_manager_$set_switch entry (char(*), char(*),
| char(*), bit(1), fixed bin(35));
| call file_manager_$set_switch (dir_name, entryname,
| switch_name, switch_value, code);
| where:
| dir_name (Input)
| is the pathname of the directory containing the DM
| file.
| entryname (Input)
| is the entry name of the DM file.
| switch_name (Input)
| is the name of the switch whose value is to be set.
| switch_value (Input)
| is the value the named switch is to be set to.
| code (Output)
| is the standard system status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$simple_get |
This entry is used to get a sequence of bytes from a Data |
Management (DM) file, given an opening id (OID), a control |
interval (CI), and control interval offset. The sequence is |
placed in a caller supplied buffer. This entry point differs |
from the get entry point in that it can only get bytes from one |
location within a control interval, and a ci_parts structure does |
not have to prepared to make the call. |
Usage |
dcl file_manager_$simple_get entry (bit(36) aligned, fixed |
bin(27), fixed bin(21), ptr, fixed bin(21)); |
call file_manager_$simple_get (oid, ci_num, |
ci_offset_in_bytes, buf_ptr, buf_length_in_bytes); |
where: |
oid (Input) |
is the opening id of the Data Management (DM) file. |
ci_num (Input) |
is the control interval in the DM file that contains |
the data to be gotten. |
ci_offset_in_bytes (Input) |
is the offset from the beginning of the control |
interval to the beginning of the data, expressed in |
bytes. |
buf_ptr (Input) |
is a pointer to a caller supplied buffer where the |
data is to be placed. |
buf_length_in_bytes (Input) |
is the length expressed in bytes of the caller |
supplied buffer. This also specifies the number of |
bytes to be fetched. The sum of ci_offset_in_bytes |
and buf_length_in_bytes must not exceed the length |
of a control interval. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$simple_put
| This entry places a given sequence of bytes into a Data
| Management (DM) file, given an open id (OID), a control interval
| (CI), and a control interval offset. This entry differs from the
| put entry point in that it will only place bytes at one given
| location within a control interval, so a ci_parts structure is
| not needed.
| Usage
| dcl file_manager_$simple_put entry (bit(36) aligned, fixed
| bin(27), fixed bin(21), ptr, fixed bin(21));
| call file_manager_$simple_put (oid, ci_num,
| ci_offset_in_bytes, buf_ptr, buf_length_in_bytes);
| where:
| oid (Input)
| is the opening id of the Data Management (DM) file.
| ci_num (Input)
| is the control interval in the DM file where the
| data is to be placed.
| ci_offset_in_bytes (Input)
| is the offset from the beginning of the control
| interval to the beginning of where the data is to be
| placed.
| buf_ptr (Input)
| is a pointer to the buffer containing the data.
| buf_length_in_bytes (Input)
| is the number of bytes that are to be placed into
| the DM file.
| code (Output)
| is the standard system status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$status |
This entry point returns status information on a Data Management |
(DM) file. This entry is currently not implemented. |
Usage |
dcl file_manager_$status entry (bit(36), ptr, fixed |
bin(35)); |
call file_manager_$status (oid, file_status_ptr, code); |
where: |
oid (Input) |
is the opening id of the DM file. |
file_status_ptr (Input) |
is a pointer to a file_status structure to be filled |
in by this entry. Currently the file_status |
structure has not been defined. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$suffix_info
| This entry point is for support of extended object software. It
| returns a suffix_info structure describing what can be done with
| Data Management (DM) files. The suffix_info structure is
| described under the notes section below.
| Usage
| dcl file_manager_$suffix_info entry (ptr);
| call file_manager_$suffix_info (suffix_info_ptr);
| where:
| suffix_info_ptr (Input)
| is a pointer to a user-supplied suffix_info
| structure.
| Notes
| The suffix_info include file is suffix_info.incl.pl1. The form
| of the structure is as follows:
| dcl 1 suffix_info aligned based (suffix_info_ptr),
| 2 version char(8),
| 2 type char(32) unaligned,
| 2 type_name char(32) unaligned,
| 2 plural_name char(32) unaligned,
| 2 flags unaligned,
| 3 standard_object bit(1) unaligned,
| 3 extended_acl bit(1) unaligned,
| 3 has_switches bit(1) unaligned,
| 3 mbz1 bit(33) unaligned,
| 2 modes char(36),
| 2 max_mode_len fixed bin,
| 2 num_ring_brackets fixed bin,
| 2 copy_flags like copy_flags,
| 2 info_pathname char(168) unaligned;
| where:
| version
| is the version mark of this structure. Currently
| SUFFIX_INFO_VERSION_1.
| type
_____________ _____________
file_manager_ file_manager_
_____________ _____________
is the type of this object. For example: DM file. |
type_name |
is the singular name of the object type. |
plural_name |
is the plural name of the object type. |
flags.standard_object |
This flag is on if this is not an extended object. |
flags.extended_acl |
This flag is on if this object uses extended ACLs. |
flags.has_switches |
This flag is on if switches are supported for the object. |
modes |
is a string containing the characters that represent the modes |
of the object. For example, modes = "rew" |
max_mode_len |
The maximum number of modes on an object. |
num_ring_brackets |
is the number of ring brackets on the object. |
copy_flags |
is the copy_flags structure which contains a list of flags |
that describe which attributes may be copied by copy_. This |
structure is defined in the include file: copy_flags.incl.pl1 |
(see below). |
info_pathname |
is the pathname of the info segment containing more |
information. |
copy_flags |
The form of the include file copy_flags is as follows: |
dcl 1 copy_flags aligned based, |
2 names bit (1) unaligned, |
2 acl bit (1) unaligned, |
2 ring_brackets bit (1) unaligned, |
2 max_length bit (1) unaligned, |
2 copy_switch bit (1) unaligned, |
2 safety_switch bit (1) unaligned, |
2 dumper_switches bit (1) unaligned, |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| 2 entry_bound bit (1) unaligned,
| 2 extend bit (1) unaligned,
| 2 update bit (1) unaligned,
| 2 mbz bit (26) unaligned;
| where:
| names
| is on if all the object names may be copied by copy_.
| acl
| is on if the access control list (ACL) may be copied by copy_.
| ring_brackets
| is on if the ring_brackets may be copied by copy_.
| max_length
| is on if the max_length may be copied by copy_.
| copy_switch
| is on if the value of the copy switch may be copied by copy_.
| safety_switch
| is on if the value of the safety switch may be copied by
| copy_.
| dumper_switches
| is on if the value of the dumper switches may be copied by
| copy_.
| entry_bound
| is on if the entry bound attribute may be copied by copy_.
| This is only used for object segments.
| extend
| is on if copy may append to the end of the existing object.
| update
| is on if copy_ may replace the contents of the existing
| object.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$terminate_ci_ptr |
This entry point releases a control interval pointer to a |
specific control interval (CI) of a Data Management (DM) file |
that has been gotten through the get_ci_ptr entry point. |
Currently this entry point is not implemented, and get_ci_ptr |
does not remember which ci_ptr it has handed out. |
Usage |
dcl file_manager_$terminate_ci_ptr entry (bit(36) aligned, |
fixed bin(27), ptr, fixed bin(35)); |
call file_manager_$terminate_ci_ptr (oid, ci_num, ci_ptr, |
code); |
where: |
oid (Input) |
is the opening id of the DM file. |
ci_num (Input) |
is the control interval that the control interval |
pointer points to. |
ci_ptr (Input) |
is the control interval pointer to be terminated. |
code (Output) |
is the standard system status code. |
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$undo
| This entry point has not been implemented. It is supposed to be
| used for rolling back any of several different kinds of actions
| that may be performed in the Data Management (DM) system, such as
| undeleting, uncreating, and unmodifying DM files.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$unput
This entry point is used exclusively by the before journal
manager for rolling back transactions. It is just like put,
except that it does not lock the control interval or journal a
before image. Also, it does not update the time_modified stamp
in the control interval header.
Usage
dcl file_manager_$unput entry (bit (36) aligned, fixed bin
(27), ptr, fixed bin (35));
call file_manager_$unput (oid, ci_num, ci_parts_ptr, code);
where:
oid (Input)
is a file opening identifier.
ci_num (Input)
is a control interval number.
ci_parts_ptr (Input)
points to the structure described under the get
primitive.
code (Output)
is a standard status code.
_____________ _____________
file_manager_ file_manager_
_____________ _____________
| Entry: file_manager_$user_shutdown
| This entry is called during the user shutdown period. Its
| function has not been defined for the File Manager. This entry
| currently is just a no-op.
| Usage
| dcl file_manager_$user_shutdown entry ();
| call file_manager_$user_shutdown ();
_____________ _____________
file_manager_ file_manager_
_____________ _____________
Entry: file_manager_$validate |
This entry point validates whether an entry is a Data Management |
(DM) file or not. |
Usage |
dcl file_manager_$validate entry (char(*), char(*), fixed |
bin(35)); |
call file_manager_$validate (dir_name, entryname, code); |
where: |
dir_name (Input) |
is the pathname of the directory containing the DM |
file. |
entryname (Input) |
is the entryname of the DM file. |
code (Output) |
is the standard system status code. Zero is |
returned if the entry is a valid DM file. If the |
entry is a DM file, then a zero status code is |
returned, otherwise one of the following is |
returned: |
error_table$noentry - File does not exist and user has "s"
access to the file's containing directory; |
error_table_$no_info - User does not have "s" access to the
file's containing directory and does not have "r" access
to the file's first component; |
error_table_$not_seg_type - File does not have the canonical
add-name on the first component which identifies it as
a DM file, or, the write-ring-bracket on the first
component is not the DM ring (here defined as the ring
of execution of this module). |