NAME_$INTRO Domain/OS NAME_$INTRO
NAME
intro - the Naming Server
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/name.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/name.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/name.ins.ftn'
DESCRIPTION
The Naming Server is the Domain/OS facility responsible for the associa-
tion of file system objects with pathnames (ASCII strings by which users
organize file system objects). As such it manages the user side of the
Domain/OS file system.
The following is a list of the name_$ calls.
name_$add_link create a link
name_$cname change a leaf name
name_$create_directory create a directory
name_$create_file create a permanent file
name_$delete_directory delete a directory
name_$delete_file delete a file
name_$drop_link delete a link
name_$extract_data_lc extract a directory entry
name_$get_ndir_lc get the naming directory
name_$get_path_lc get a full pathname
name_$get_wdir_lc get the working directory
name_$read_dir_lc read a directory
name_$read_link_lc return the pathname associated with a link
name_$set_ndir set the naming directory
name_$set_wdir sets the working directory
The Naming Server presents a familiar hierarchical file system to the
user. Objects have names and are grouped in directories. Directories
are objects too, and may contain other directories. The resulting tree
structure descends from a network root, represented by a double slash
(//), through a branching network of directory names, delimited by single
slashes (/), to terminating "leaf names."
Absolute Pathnames
Pathnames that begin with a slash (/) are called "absolute pathnames."
An absolute pathname can start at the network root (//) or the node entry
directory (/).
The most specific pathname recognized by the Naming Server is an absolute
pathname that begins at the network root (//), also known as a "full
pathname." An absolute pathname from the network root is good anywhere
in a Domain internet. No matter where it is used, the pathname will
always denote the same location in the network naming tree. Conse-
quently, it can be shared between processes running on different nodes.
For example, the master copy of a network database might reside at
//master/database/index. A Naming Server will always treat the pathname
//master/database/index as a reference to the network-wide master data-
base, no matter which node it is running on.
The next most specific pathname is an absolute pathname rooted at the
node entry directory (/). An absolute pathname rooted at the node entry
directory defines a set of possible positions in the naming tree, one on
each node. For instance, the object that the pathname /sys/node_data
refers to will depend on which node it is used on.
An absolute pathname rooted at the node entry directory lacks any infor-
mation to discriminate between nodes and, therefore, refers to as many
different locations in the network naming tree as there are nodes on a
network. An absolute pathname rooted at the node entry directory is a
useful mechanism for defining a position local to a node independently of
any particular node's name.
In summary, an absolute pathname from the network root defines a unique
position in the network, whereas an absolute pathname rooted at the node
entry directory defines a unique position on a node.
Relative Pathnames
Pathnames that don't begin with a slash are called "relative pathnames."
Relative pathnames define positions relative to either the "naming direc-
tory" or the current "working directory."
The naming directory is a per-process pathname defined by the
name_$set_ndir_lc call. The Naming Server substitutes the naming direc-
tory for the tilde character (~) whenever it occurs in the string "~/" at
the beginning of a pathname. The naming directory is supported mainly as
a convenient abbreviation in command shells and is not terribly useful to
programmers.
All pathnames that do not begin with "/", "//", or "~/" are interpreted
relative to the current working directory. The current working direc-
tory is a per-process pathname defined by the name_$set_wdir_lc call.
When the Naming Server sees a relative pathname that does not begin with
"~/" it effectively uses the current working directory as a prefix to
arrive at an absolute pathname, then uses the resulting absolute pathname
to find the object.
Variable Pathnames
A variable pathname is a pathname that resolves to different positions in
the naming tree depending on the values of the variable names embedded in
it. A variable name has the form $(variable), where variable is an
environment variable. When the Naming Server encounters a variable name,
it substitutes the current value of variable and continues the name reso-
lution process. Variable pathnames are most frequently used to create
conditional branches in the naming tree that depend on the environment a
process is running in. They cause the Naming Server to present different
naming trees to different environments.
Dotdot and Dot
It is sometimes instructive to think that the Naming Server makes all the
preliminary substitutions described previously, then starts from the net-
work root, and processes a pathname a name at a time until it reaches the
leaf name and finds the referenced object. While processing a pathname,
the Naming Server may encounter two entries that are present in every
directory: ".." (dotdot) and "." (dot), which are links to "the parent
of the current directory" and "the current directory," respectively.
A directory is said to be a "parent" of the objects named in it. Every
location in the naming tree has exactly one real parent, the directory
its leaf name is cataloged in. The node entry directory's parent is the
network root, and the network root's parent is itself.
The directory entry ".." is linked to the parent of of its directory.
Thus, the pathname /user/user_data/mail/../source refers to the same
location in the naming tree as /user/user_data/source, barring any user-
defined links in /user/user_data. Dotdot is most often used at the
beginning of a pathname where it denotes the parent of the working direc-
tory. For example, ../filename refers to the object named filename in
the parent of the working directory, and .. by itself is the pathname of
parent directory of the current working directory.
The entry "." is linked to the current directory itself. When single
dot is preceded or followed by a slash, the Naming Server effectively
ignores the sequence when processing the pathname. A pathname consisting
entirely of dot by itself is equivalent to the current working directory.
Although dot and dotdot are sometimes convenient, they can be tricky when
used in an environment that is as liberal about links as Domain/OS. For
instance, if there are links in /user/user_data (other than the system-
supplied entries ".." and "."), then the pathnames
/user/user_data/mail/../source and /user/user_data/source may not refer
to the same object.
Links
The basic tree structure described above, in which there is a unique path
from the network root to every branch and leaf name, can be perturbed by
the presence of links in the naming tree. A link is a directory entry
associated with another pathname, rather than with a file system object;
it links two positions in the naming tree by providing a new pathname for
a position in the naming tree already defined by another pathname. If
the Naming Server encounters a link while resolving a pathname, it sub-
stitutes the pathname contained in the link for the path that led to the
link.
Links are used mainly to localize references to resources that are actu-
ally distributed around the network, or to provide short cuts to fre-
quently accessed objects. The most common links are those that bring an
object cataloged on a remote node into the naming tree of the local node.
For example, a link at /sys/print to //printer1/sys/print brings the job
queue and print spool of the //printer node into the naming tree of the
local node, where they can be accessed via a pathname beginning with the
node entry directory rather than with the network root.
Links are created by name_$add_link and deleted by name_$drop_link. The
directory containing a link is not the parent of the pathname the link
points to, and a dotdot following a link will not return the Naming
Server to the link's branch of the naming tree. A call to name_$add_link
does not create another parent for a pathname. The pathname linked to
still has only one parent, the directory its leaf name is cataloged in.
Likewise name_$drop_link cannot delete an object, though
name_$delete_file can leave a dangling link, a link that does not resolve
to any existing directory entry.
Constants
name_$long_complen_max
The maximum number of bytes in a leaf name.
name_$file
Used in the enttype field of a name_$canonical_dir_entry_t record to
indicate that the directory entry is for a file.
name_$link
Used in the enttype field of a name_$canonical_dir_entry_t record to
indicate that the directory entry is for a link.
name_$long_pnamlen_max
The maximum number of bytes in a pathname.
Data Types
name_$buf_t
A large buffer for the receipt of a variable number of directory
entries in name_$canonical_dir_entry_t records.
name_$canonical_dir_entry_t
A record for holding a directory entry as returned by
name_$read_dir_lc.
15 0
______________________________________________________________
| entnxt |
|_____________________________________________________________|
| enttype |
|_____________________________________________________________|
| reserved1 |
|_____________________________________________________________|
| reserved1 |
|_____________________________________________________________|
| reserved2 |
|_____________________________________________________________|
| reserved2 |
|_____________________________________________________________|
| reserved3 |
|_____________________________________________________________|
| reserved3 |
|_____________________________________________________________|
| enthandle |
|_____________________________________________________________|
| enthandle |
|_____________________________________________________________|
| entlen |
|_____________________________________________________________|
| entname | ... |
______________________________________________________________
15 8 7 0
entnxt
An offset in bytes to the next entry in a list of directory
entries.
enttype
The type of the directory entry. It can be one of the follow-
ing types:
name_$file
The directory entry is for a file.
name_$link
The directory entry is for a link.
reserved1
Reserved for use by Domain/OS.
reserved2
Reserved for use by Domain/OS.
reserved3
Reserved for use by Domain/OS.
enthandle
A handle to the directory used by Domain/OS.
entlen
The number of bytes in entname.
entname
The directory entry name of type name_$long_name_t.
name_$cursor_t
A data structure used by name_$read_dir_lc to keep its place through
successive calls on a directory. The calling program should not
change arguments of type name_$cursor_t.
name_$long_name_t
A null-terminated string up to name_$long_complen_max bytes long
used to specify leaf names.
name_$long_pname_t
A null-terminated string up to name_$long_pnamlen_max bytes long
used to specify pathnames.
Errors
name_$already_exists
The proffered name already exists.
name_$bad_directory
Invalid directory.
name_$bad_leaf
Invalid leaf.
name_$bad_link
Invalid link.
name_$bad_pathname
Invalid pathname.
name_$directory_full
The directory named is full.
name_$directory_not_empty
The directory is not empty.
name_$file_not_directory
The proffered pathname is not a directory.
name_$ill_link_op
Invalid link operation.
name_$insufficient_rights
The calling program lacks sufficient rights to perform the requested
operation.
name_$is_sysboot
The calling program attempted to delete the system bootstrap (sys-
boot).
name_$leaf_truncated
The supplied buffer was not large enough to receive the requested
leaf name, so it was truncated.
name_$no_rights
The calling process has no rights to the proffered name.
name_$node_unavailable
Node is unavailable.
name_$not_file
The proffered name is not a file.
name_$not_found
The proffered name could not be found.
name_$not_link
The proffered name is not a link.
name_$pathname_truncated
The supplied buffer was not large enough to receive the requested
pathname, so it was truncated.