.th UDM VIII 4/21/86
.sh NAME
UDM - UNIX Directory Manager.
.sh DESCRIPTION
UDM maintains a UNIX-like directory structure on top of a KSOS file
system.  All directory operations, creating entries, removing entries
and searching directories is supported by the directory manager and
directory manager interface procedures.
.s3
Directories are of a distinguished subtype known as the directory
subtype.  The directory subtype is used to insure that the UDM is the
only process that is allowed to write directories.  However, other
processes may open directories for reading by presenting a read
directory subtype open descriptor to K_open.
.s3
Access to the directory manager is provided by the directory manager
interface, which must be compiled with the program which plans to use
it.  The directory manager interface provides a procedure call
interface to the UDM.  The interface handles the packing of a UDM
argument block, the building of an argument segment, the spawning of
the UDM and the waiting for IPC status return.
.sh DEFINITIONS
.lp 12 7
Path Name -
A path name is a character array of directory
names, where the character "/" is used to separate directory names.
.s3
.lp 12 7
Leaf Name -
The leaf component of a path name is the last name in a path name.
.s3
.lp 12 7
Starting Directory -
Directory operations take a path name and a starting directory (seid)
as arguments.
If a rooted path name
(a path name that begins with "/")
is given to a directory manager interface procedure,
the directory operation assumes the root directory as the starting
directory regardless of the starting directory given.
.s3
.lp 12 7
Directory Subtype -
The directory subtype is a well known seid.
.br
.nf
	seid (subtype_nsp, char(100) cardinal (0))
.fi
All directories are of directory subtype.
.s3
.lp 12 7
Root Directory -
The seid of the first mounted file system, which is know as the root
file system, is:
.br
.nf
	seid (root_nsp, char(0) cardinal (5))
.fi
.s3
.lp 12 7
UDM Event Type -
The directory manager process communicates status information to its parent,
the directory manager interface procedure, via an IPC.
The first byte of the message portion of the IPC contains the event type
of the IPC.
The
IPC returned from the directory manager shall always have
event type 26 decimal.
.s3
.lp 12 7
UDM_error -
UDM_error
is an enumerated type that is declared in UDM interface.
Its MODULA definition is:
.nf

	UDM_error = (UDM_no_error,
		     UDM_cannot_do,
		     UDM_cannot_link,
		     UDM_cannot_unlink,
		     UDM_entry_exists,
		     UDM_entry_does_not_exist,
		     UDM_cannot_open_directory,
		     UDM_seid_refers_to_a_directory,
		     UDM_cannot_create_directory,
		     UDM_cannot_remove_directory,
		     UDM_directory_not_empty,
		     UDM_not_directory,
		     UDM_directory_not_writable,
		     UDM_not_executable,
		     UDM_no_path,
		     UDM_not_found,
		     UDM_cannot_link_across_file_systems,
		     UDM_cannot_mount,
		     UDM_cannot_unmount);

.fi
Note that an enumerated type in MODULA begins at zero.
.i0
.bp
.sh "INTERFACE PROCEDURE"
UDM_mkentry - make a directory entry
.sh "MODULA SYNOPSIS"
.nf
CONST     SEID_of_dir       : seid;
CONST     SEID_of_entry     : seid;
CONST     path_name         : ARRAY integer OF char;
CONST     wait_flag         : boolean;
CONST     UDM_stat          : UDM_error;

...

UDM_stat := UDM_mkentry ( SEID_of_dir,
			  SEID_of_entry,
			  path_name,
			  wait_flag);
.fi
.sh DESCRIPTION
The UDM_mkentry procedure causes a directory entry to be made.
Starting at the directory specified by SEID_of_dir, the components of
the path name "path_name" are used to find subordinate directories
until only a leaf component of the path name remains.  A directory
entry is then made in the parent directory of the leaf name.  This
directory entry is composed of the SEID_of_entry and the leaf component
of path_name.  Seids with any name space may be used as a
SEID_of_entry.  However seids with a file name space shall be linked.
.s3
The
wait_flag
specifies if the directory operation is to be synchronous or asynchronous.
If the
wait_flag
is true then the procedure shall not return until an IPC status block
is received from the
UDM.
.s3
Note that files are created with a zero link count and remain in existence
so long as they are open or have a non-zero link count.
Therefore, the proper way to make a directory entry for a newly created
file is to create the file, call
UDM_mkentry,
and then close the file.
.sh DIAGNOSTICS
UDM_mkentry
returns the following error codes:
.in +5
.nf
UDM_no_error
UDM_cannot_link
UDM_entry_exists
UDM_cannot_open_directory
UDM_seid_refers_to_a_directory
UDM_cannot_link_across_file_systems
.in -5
.bp
.sh "INTERFACE PROCEDURE"
UDM_mkdir - create a directory
.sh "MODULA SYNOPSIS"
.nf
CONST     SEID_of_dir     : seid;
CONST     dir_name        : ARRAY integer OF char;
CONST     wait_flag       : boolean;
VAR       UDM_stat        : UDM_error;

   ...

UDM_stat := UDM_mkdir ( SEID_of_dir,
			dir_name,
			wait_flag);
.fi
.sh DESCRIPTION
UDM_mkdir
creates a directory.
Starting at the directory specified by
SEID_of_dir
the components of the path name
"dir_name"
are used to find subordinate directories until the last parent directory
component is found.
A directory is then created in the parent directory with the name of the
leaf name.
This newly created directory shall have access modes of read, write,
execute by owner
and read, execute by group and others.
Also, this directory shall contain two distinguished directory entries,
"." and "..".
The "." directory entry shall refer to the newly created directory and
the ".." directory entry shall refer to the parent directory.
.s3
The
wait_flag
specifies if the directory operation is to be synchronous or asynchronous.
If the
wait_flag
is true then the interface procedure shall not return control to the caller
until an IPC status block
is received from the UDM.
.sh DIAGNOSTICS
UDM_mkdir returns the following error codes:
.in +5
.nf
UDM_no_error
UDM_entry_exists
UDM_cannot_open_directory
UDM_cannot_create_directory
.in -5
.fi
.bp
.sh "INTERFACE PROCEDURE"
UDM_rm - remove a directory entry
.sh "MODULA SYNOPSIS"
.nf
CONST     SEID_of_dir     : seid;
CONST     path_name       : ARRAY integer OF char;
CONST     wait_flag       : boolean;
VAR       UDM_stat        : UDM_error;

 ...

UDM_stat := UDM_rm ( SEID_of_Dir,
		     path_name,
		     wait_flag);

.fi
.sh DESCRIPTION
The
UDM_rm
procedure causes a directory entry, which may be a file or directory,
to be removed.
Starting at the directory specified by
SEID_of_Dir
the components of the path name
"path_name"
are used to find subordinate directories until only a leaf
component of the path name remains.
The leaf name directory entry is then removed.
If the directory entry to be removed is a file,
K_unlink
is called.
If the directory entry to be removed is an empty directory,
consisting of only "." and ".." entries,
the directory is removed.
.s3
The
wait_flag
specifies if the directory operation is to be synchronous or asynchronous.
If the
wait_flag
is true then the procedure shall not return until a IPC status block
is received from the
UDM.
.sh DIAGNOSTICS
UDM_rm
returns the following error codes:
.in +5
.nf
UDM_no_error
UDM_not_found
UDM_cannot_unlink
UDM_directory_not_empty
UDM_cannot_open_directory
UDM_cannot_remove_directory
.in -5
.fi
.bp
.sh "INTERFACE PROCEDURE"
UDM_find - Path Interpretation.
.sh "MODULA SYNOPSIS"
.nf
CONST     starting_dir_seid     : seid;
CONST     path_name             : ARRAY integer OF char;
CONST     operation             : pathOp;
VAR       parent_dir_seid       : seid;
VAR       entry_seid            : seid;
VAR       entry_name            : ARRAY integer OF char;
VAR       UDM_stat              : UDM_error;

 ...

UDM_stat := UDM_find (starting_dir_seid,
		      path_name,
		      operation,
		      parent_dir_seid,
		      entry_seid,
		      entry_name);

.fi
.sh DESCRIPTION
UDM_find
performs path interpretation operations.
Starting at the directory specified by
starting_dir_seid,
the components of the path name
"path_name"
are used to find subordinate directories until only a leaf
component of the path name remains.
The path operation specified by
operation
is then performed.
.s3
For all directory operations, if
the path name to the parent directory of the leaf name is
legal, then the
parent_dir_seid
is filled with the seid of the parent directory and
the
entry_name
is filled with the leaf name.
If the
entry_name
directory entry exists
then
entry_seid
is filled with the seid of that directory entry.
.s3
The following path operations are defined:
.s3
.lp 14 4
po_mkentry - checks
if a directory entry of the specified name can be made.
A status of
UDM_no_error
is returned if the process has write permissions in the
parent directory and if the entry of the desired name does
not exist.
.s3
.lp 14 4
po_remove - determines
if the directory entry of the specified name can be removed.
A status of
UDM_no_error
is returned if the process has write permissions in the
parent directory and the leaf name directory entry exists.
If the leaf name is a directory, that directory must only contain the
"." and ".." directory entries.
.s3
.lp 14 4
po_locate - determines
if a directory entry of the specified name exists.
A status of
UDM_no_error
is returned if the entry is found.
.s3
.lp 14 4
po_chdir - checks
if the specified directory entry is a directory and that the
process has search/execute permissions for that directory.
If the above checks are satisfied, a status of
UDM_no_error
is returned.
.s3
.lp 14 4
po_exec - checks
if the specified directory entry exists and is an executable file.
A status of
UDM_no_error
is returned if the process has execute permissions for that file and
if the file contains the magic numbers (ala UNIX).
.i0
.sh DIAGNOSTICS
UDM_find returns the following error codes:
.in +5
.nf
UDM_no_error
UDM_no_path
UDM_cannot_do
UDM_not_found
UDM_entry_exists
UDM_not_directory
UDM_cannot_open_directory
UDM_directory_not_writable
.in - 5
.fi
.bp
.sh "USING THE UDM INTERFACE"
Two UDM interfaces exist, one for supervisor MODULA programs and one
for supervisor C programs.  For C, #include the files KERcalls.h and
EDI.h, the loader will resolve the UDM interface at link time.
.s3
To use the UDM interface for MODULA one must:
.s3
.lp 14 4
a)  Define the following C pre-processor (cpp) constants: k_bldseg, k_invoke, k_spawn,
k_getps, k_relseg, k_getss, k_setss, k_setps, and k_setda.
Defining these constants allows the related kernel calls to
be conditionally compiled with the source.
.s3
.lp 14 4
b)  Include KERcalls.mod.
.s3
.lp 14 4
c)  Define the constant
ipc_on for cpp.
This constant allows the IPC handling procedure to be
compiled.
.s3
.lp 14 4
d)  Declare the procedure IPC_valid.
This procedure is imported into the pseudo-interrupt handling module
and it is used to check the validity of an ipc before it is put
on the IPC queue.
This procedure allows a process to guarantee that its IPC
queue will not get filled with unwanted IPC's.
The procedure,
IPC_valid
should take an
ipc_block
as a parameter and should return a boolean result.
True if the IPC is to be placed on the queue and false
if the IPC is to be discarded.
.s3
.lp 14 4
e)  Include the pseudo-interrupt handling module
npi.mod.
.s3
.lp 14 4
f)  Include the UDM directory manager interface for MODULA.
.i0
.sh FILES
.nf
KERcalls.mod      Kernel interface for MODULA
KERcalls.h        Kernel interface for C
udm_lib.mod       UDM interface for MODULA
EDI.h             UDM interface for C
npi.mod           Pseudo-interrupt handling module
.fi
.sh "SEE ALSO"
ipc_block (IIa),
seid (IIa),
APPENDIX B
