1 01/29/86  extended_entries.gi
 2 
 3 An extended entry is a storage system entity that is created and
 4 manipulated by a particular subsystem and for which the operations
 5 performed by the standard file system commands and subroutines are
 6 either incorrect or impossible.  For example, the mailbox is created
 7 and maintained by the message segment facility.  All mailboxes must be
 8 named with the suffix ".mbx" and their accessibility is defined by
 9 extended modes instead of the more familiar "rew" or "sma" modes.  In
10 addition, proper access to these entries is enforced by the fact that
11 they are ring 1 residents: they are inaccessible from the user ring
12 unless message_segment software (ring 1 resident) is invoked through a
13 gate.
14 
15 
16 Extended entry software allows the standard Multics commands and
17 subroutines to operate upon extended entries without compromising the
18 integrity of the owning subsystem.  This applies not only to bundled
19 extended entries, such as mailboxes and message segments, but also to
20 user-written subsystems.
21 
22 A number of commands and subroutines have been modified to handle
23 correctly extended entries.  These include add_name, copy, copy_acl,
24 copy_dir, copy_names, delete, delete_acl, delete_name, list_acl, move,
25 move_dir, rename, set_acl, set_max_length, set_ring_brackets, status,
26 switch_on, switch_off, copy_, copy_dir_, copy_acl_, copy_names_,
27 delete_, dl_handler_, nd_handler_.
28 
29 
30 There are two new commands for printing information about extended
31 entries.  The list_entry_types command prints a list of all the entry
32 types that you can find in the search rules.  It provides only the
33 name of the entry type and the suffix it uses.  For detailed
34 information about an entry type, use describe_entry_type.  It prints
35 out the name of the type, various attributes, and the pathname of an
36 info segment containing more information about the entry type.  The
37 status commands now accepts a -type control argument, which prints the
38 type of a storage system entry, be it extended (as for mailboxes) or
39 standard (segment, directory, etc.).
40 
41 
42 The extended entry facility is implemented by the fs_util_ subroutine.
43 The entry points in fs_util_ are used to change and retrieve
44 information about any file system entry.  The fs_util_ subroutine
45 determines whether or not the entry is extended by examining its
46 suffix.  Assuming that the suffix is XXX, fs_util_ attempts to locate
47 and then invoke a subroutine named "suffix_XXX_$validate".  If both
48 of these actions succeed, the entry is considered to be extended and
49 subsequently referenced through suffix_XXX_; otherwise it is
50 considered standard, and fs_util_ decides how to reference it.
51 
52 To enable an application program to operate upon extended entries, the
53 hcs_ calls it makes to perform file system operations should be
54 replaced by the corresponding fs_util_ calls.  Calls to any one of the
55 standard system subroutines listed above, which already support
56 extended entries, need not be changed.
57 
58 
59 To implement an extended entry type, you must choose a suffix and
60 implement a suffix support routine for that entry type.  Each suffix
61 support routine must support the suffix_info and validate entrypoints,
62 as well as a few optional ones.  These routines are called by
63 fs_util_.  If any of the optional entry points are not provided,
64 fs_util_ returns an error code of error_table_$unsupported_operation
65 to its caller and the particular operation fails.
66 
67 
68 There are two restrictions in implementing an extended entry type.
69 First, an extended entry type can use only standard entry types, i.e.,
70 segment, directory, multisegment_file, and dm_file, as the underlying
71 storage type.  Second, if the acl modes for the extended entry type do
72 not map directly onto the standard modes, then they must be stored in
73 the extended modes field of hte underlying type.  For example:
74 mailboxes use the extended modes field of segments to store their
75 modes of "adroswu".