PH(1L) UNIX Programmer's Manual PH(1L)
NNAAMMEE
ph - CCSO Nameserver client (on-line phone book)
SSYYNNOOPPSSIISS
pphh [ --ss _s_e_r_v_e_r ] [ --pp _p_o_r_t ] [ --tt _t_y_p_e ] [
--ff _f_i_e_l_d_1,_f_i_e_l_d_2,... ] [ --mmMMrrRRbbBBTTllLLFF ] query
pphh [ --ss _s_e_r_v_e_r ] [ --pp _p_o_r_t ] [ --tt _t_y_p_e ] [
--ff _f_i_e_l_d_1,_f_i_e_l_d_2,... ] [ --hh _t_o_p_i_c ] [ --mmMMnnNNrrRRbbBBTTllLLFFccCC
DDEESSCCRRIIPPTTIIOONN
_P_h queries the CCSO Nameserver, a database of University
faculty, staff, and students. The database contains nearly
all the information in the _S_t_u_d_e_n_t/_S_t_a_f_f _D_i_r_e_c_t_o_r_y (the
University phone book), as well as other information,
including electronic mail addresses.
_P_h may be used in two ways; interactively or with command-
line arguments.
If given arguments, _p_h will treat the arguments as a query
and return the results of the query. For example,
ph paul pomes
would return the entry for the maintainer of _p_h , Paul
Pomes. For more information on what types of queries you
may make, see the QQUUEERRIIEESS section below.
If given no arguments, _p_h will enter interactive mode, print
a prompt, and wait for commands. Interactive mode will be
discussed in detail below.
_P_h is not intended for the generation of mailing lists.
Therefore, it will refuse any requests resulting in more
than a small number of matches. This is not negotiable.
OOPPTTIIOONNSS
_P_h recognizes the following options. They may be specified
in the _P_H environment variable, given on the command line,
or set with the sswwiittcchh command from inside _p_h. Options
given with the sswwiittcchh command override all others; options
given on the command line override those in the _P_H environ-
ment variable.
--nn Do not read the ._n_e_t_r_c file. This option has meaning
only when using _p_h in interactive mode (see below for
descriptions of the ._n_e_t_r_c file and interactive mode).
--NN Do read the ._n_e_t_r_c file. This is the default.
--rr Do not reformat _a_l_i_a_s and _e_m_a_i_l fields to show alias-
based e-mail addresses.
Printed 8/30/92 30-Jul-1992 1
PH(1L) UNIX Programmer's Manual PH(1L)
--RR Reformat _a_l_i_a_s and _e_m_a_i_l fields to show alias-based e-
mail addresses. This is the default.
--bb Do not beautify query responses; print them in gory
detail, complete with response codes.
--BB Beautify query responses. This is the default.
--mm Do not use a paging program (like _m_o_r_e(1)) when print-
ing responses.
--MM Use a paging program. This is the default.
--ll Do not label field values with field names when print-
ing queries.
--LL Label field values with field names when printing
queries. This is the default.
--tt _t_y_p_e
Use _t_y_p_e as a default type on queries. This is just
like adding ttyyppee==_t_y_p_e to all queries. The --tt option
can be overriden by specifying an explicit type in the
query, as in, "ph pomes type=phone""..
--TT Do not specify any type by default; this is the
default.
--ss _s_e_r_v_e_r
Use _s_e_r_v_e_r as a Nameserver host, instead of the default
host. A list of suitable servers may be found with the
query "ph alias=ns-servers".
--pp _p_o_r_t
Connect to the tcp port _p_o_r_t, instead of the default
port.
--cc Do not wait for confirmation of edit commands. This is
the default.
--CC Wait for confirmation of edit commands (see eeddiitt
below).
--ff _f_i_e_l_d_1,_f_i_e_l_d_2,...
Return fields _f_i_e_l_d_1,_f_i_e_l_d_2,... instead of the default
list of fields, if no return clause is specified on
queries. This is just like adding "return field1
field2 ..." _t_o _a_l_l _q_u_e_r_i_e_s.
--FF Return default list of fields; this is the default.
--hh _t_o_p_i_c
Printed 8/30/92 30-Jul-1992 2
PH(1L) UNIX Programmer's Manual PH(1L)
Display a list of on-line help topics. If the --hh
option is followed by the name of one of the on-line
help topics, the help screen for _t_o_p_i_c will be
displayed.
QQUUEERRIIEESS
The Nameserver's database contains over 70,000 entries.
Each entry is comprised of multiple _f_i_e_l_d_s, each containing
information about the entry. Each field has a name that is
descriptive of what the field contains; for example, the
field named _a_d_d_r_e_s_s contains the office mail address of the
person in question (for more information on fields, see the
description of the ffiieellddss command in the IINNTTEERRAACCTTIIVVEE section
below).
By default, queries are assumed to refer to the _n_a_m_e or
_n_i_c_k_n_a_m_e field of the entry. Therefore, saying "ph john
doe" _l_o_o_k_s _f_o_r _e_n_t_r_i_e_s _w_h_o_s_e _n_a_m_e or _n_i_c_k_n_a_m_e field contains
"john" and "doe". Fields other than the _n_a_m_e and _n_i_c_k_n_a_m_e
fields must be specified; for example,
ph pomes address=DCL
would return entries with _n_a_m_e or _n_i_c_k_n_a_m_e "pomes" whose
_a_d_d_r_e_s_s contained "DCL."
Matching in _p_h is done on a word-by-word basis. That is,
both the query and the entry are broken up into words, and
the individual words are compared. Although _p_h is insensi-
tive to case, it otherwise requires words to match exactly,
with no characters left over; "john" does nnoott match "john-
son", for example. This behavior may be overriden by the
use of normal shell metacharacters ("?" to match any single
character, "*" to match zero or more characters, and "[]" to
match a single character from a set of characters).
_P_h will display only entries that match aallll of the specifi-
cations in the query. For example,
ph paul pomes
will return all entries with bbootthh "paul" and "pomes" in the
_n_a_m_e or _n_i_c_k_n_a_m_e fields.
_P_h returns a certain set of fields by default. It is possi-
ble to ask for different fields in a query. This is done by
specifying the _r_e_t_u_r_n keyword and listing the fields of
interest. For example,
ph paul pomes return email
Printed 8/30/92 30-Jul-1992 3
PH(1L) UNIX Programmer's Manual PH(1L)
would print only the electronic mail address of the main-
tainer of _p_h. You may also ask for all fields in the entry
by using "all" as a field name. This will show you every
field you are allowed to see in the entry.
All output from _p_h is sent through _m_o_r_e(1) (or whatever pro-
gram is specified in the _P_A_G_E_R environment variable).
IINNTTEERRAACCTTIIVVEE MMOODDEE
If _p_h is given no arguments, it enters interactive mode,
where it prompts for, executes, and displays the results of
Nameserver commands. Interactive mode provides access to
more Nameserver features than mere queries. Some of these
features require the user to identify him/her self to _p_h by
use of the llooggiinn command; others do not. Commands may be
abbreviated, provided enough characters are given to distin-
guish them from other commands.
._n_e_t_r_c file
_P_h reads the same ._n_e_t_r_c file as does ftp (see _f_t_p(1)).
If it finds a _m_a_c_h_i_n_e named "ph" that has a login and a
password specified for it, _p_h will automatically do a
_l_o_g_i_n command, using the values from the ._n_e_t_r_c file.
_P_h will silently refuse to use a ._n_e_t_r_c file that has
any permissions for group or other (see _c_h_m_o_d(1)).
PPuubblliicc CCoommmmaannddss
The following commands do not require the user to be logged
in to the Nameserver:
hheellpp [_t_o_p_i_c]
Provides explanations of Nameserver commands.
Given no arguments, hheellpp lists the available help
topics. Given a _t_o_p_i_c as an argument, hheellpp will
print help for that topic. A list of commands and
a one-line description of each command may be
obtained by requesting the topic _c_o_m_m_a_n_d_s.
qquueerryy Performs Nameserver queries exactly like non-
interactive _p_h queries except that metacharacters
do not have to be quoted.
ffiieellddss Lists the fields currently in use in the
Nameserver. For each field, a display like the
following (admittedly ugly) is produced:
-200:2:email:max 64 Lookup Public Default Change
-200:2:email:Preferred electronic mail address.
...
Printed 8/30/92 30-Jul-1992 4
PH(1L) UNIX Programmer's Manual PH(1L)
The leading number is a reply code from the
Nameserver. The next number is the field number.
Following the field number is the name of the
field, the maximum length of the field, and the
attributes for the field. The second line has, in
addition to repeated reply code, number, and name,
a one-line description of the field.
The attributes determine how a field may be used.
_L_o_o_k_u_p means the field may be searched in a query.
_I_n_d_e_x_e_d means the field is indexed (at least one
_I_n_d_e_x_e_d field must be included in every query).
_D_e_f_a_u_l_t means the field is displayed by default.
_C_h_a_n_g_e means that users may change the field.
sseett _o_p_t_i_o_n[=_v_a_l_u_e]
Allows Nameserver options to be set. These
options are for future use.
sswwiittcchh -_o_p_t_i_o_n [_v_a_l_u_e]
Allows _p_h options to be set. See the OOPPTTIIOONNSS sec-
tion above.
qquuiitt Exits _p_h.
llooggiinn _a_l_i_a_s
Identifies the user to the Nameserver. _A_l_i_a_s is
your Nameserver alias, a unique name for you in
the Nameserver; it is printed in _p_h queries, as
the first thing after "email to:":
email to:
[email protected] (
[email protected])
In this case, the alias is "p-pomes". You will be
prompted for your Nameserver password when you
give the llooggiinn command, unless you are using _p_h
from the login in your email field (the one in
parentheses on the "email to:" line), and your
system administrator has made _p_h "setuid root", in
which case no password will be required.
Your Nameserver password is nnoott the same as your
system password; the only way to discover your
Nameserver password is to bring yourself and a
University ID to the CCSO Accounting Office in
1420 DCL. Because of abuses in the past, pass-
words cannot be given out via email, phone, or to
third parties.
You are allowed to change your Nameserver alias;
there are, however, restrictions on Nameserver
aliases; they must be unique within the
Printed 8/30/92 30-Jul-1992 5
PH(1L) UNIX Programmer's Manual PH(1L)
Nameserver, they cannot be common names ("david"
is right out), and they can only contain letters,
digits, dashes (-) and periods (.).
CCoommmmaannddss RReeqquuiirriinngg LLooggiinn
The following commands require that the user executing them
be logged in to the Nameserver.
ppaasssswwdd [_a_l_i_a_s]
Changes your Nameserver password. You will be
asked to type your new password twice. _P_h will
complain if your password is too short or contains
only numbers (although it does allow such pass-
words). Privileged users may change the passwords
of certain other users by specifying the alias of
the other user when giving the ppaasssswwdd command.
mmee Lists the Nameserver entry of the currently
logged-in user.
eeddiitt _f_i_e_l_d [_a_l_i_a_s]
Allows _p_h users to change those fields in their
entry that have the _C_h_a_n_g_e attribute set. _E_d_i_t
will retrieve the value of the named field (if a
value exists), and will allow the user to edit the
value with _v_i(1) (the _E_D_I_T_O_R environment variable
may be used to override the use of _v_i). The
changed value will then be reinserted in the
Nameserver. If the --CC option is in effect, the
message, "Change the value [y]?" will be printed
after the editing is finished. Pressing return
alone, or anything beginning with "y", will make
_p_h change the value; anything beginning with "n"
will make _p_h discard the changes.
mmaakkee _f_i_e_l_d=_v_a_l_u_e [_f_i_e_l_d_2=_v_a_l_u_e_2...]
Allows _p_h users to change those fields in their
entry that have the _C_h_a_n_g_e attribute set. MMaakkee
will set the specified field(s) to the specified
value(s) in the entry of the currently logged in
user.
aadddd Adds entries to the Nameserver. This is a
privileged command.
ddeelleettee Deletes entries from the Nameserver. This is a
privileged command.
llooggoouutt Undoes the effects of a llooggiinn command.
Printed 8/30/92 30-Jul-1992 6
PH(1L) UNIX Programmer's Manual PH(1L)
QQUUEERRYY EEXXAAMMPPLLEESS
Here are some examples to clarify _p_h queries. Each example
is preceded by a description of the desired effect. It is
assumed that the queries are being done with _p_h from the
command line, rather than by using the interactive mode of
_p_h. The only difference for interactive mode is that meta-
characters would not have to be quoted or escaped.
Find the _p_h entry for Paul Pomes:
ph paul pomes
Find the _p_h entry for P. Pomes, where the rest of the first
name is not known:
ph p\* pomes
Find Alonzo Johnson (or is that JohnsEn?):
ph alonzo johns\?n
or
ph alonzo johns\[eo\]n
Find Paul P., where the rest of the last name is unknown:
ph paul p\*
The last query fails because it matches too many entries.
It is therefore necessary to narrow the search. Suppose it
is known that Paul P. has an office in DCL:
ph paul p\* address=DCL
Alternately, suppose Paul P. works for CCSO. You might try:
ph paul p\* department=CCSO
When that failed, a good next guess would be:
ph paul p\* department=computing
The moral of the story is that fields in _p_h generally con-
tain whatever the user wishes them to contain, and, hence,
there may be many different spellings and abbreviations for
any particular field (some fields are exceptions, including
the _n_a_m_e field, which is always the full name, as known to
the University, of the person involved). It pays to make
liberal use of metacharacters and creativity when searching
fields other than _n_a_m_e.
Suppose all that is wanted is the full name and electronic
mail address of P. Pomes:
Printed 8/30/92 30-Jul-1992 7
PH(1L) UNIX Programmer's Manual PH(1L)
ph p\* pomes return name email
RREENNAAMMIINNGG PPHH
If _p_h is invoked with a name other than _p_h, slightly dif-
ferent option processing is done. For the sake of an exam-
ple, let us assume _p_h was invoked with the name, "unit".
The following consequences obtain:
_P_h will assume an option of "-t unit". _P_h will read the
_U_N_I_T environment variable, aafftteerr reading the _P_H environment
variable, and bbeeffoorree reading command-line options.
This feature allows the easy installation of entry-type
specific lookup commands, as well as custom configuration of
those commands.
BBUUGGSS
Separate words in a query are allowed to match the same word
in the entry; "ph s\* smith" is functionally equivalent to
"ph smith", because the "s*" is allowed to match "smith".
_P_h does some looking about in the commands you give it, but
does not understand the full syntax of Nameserver commands.
This can occasionally lead to mistakes, especially when
dealing with quoted strings.
DDIISSTTRRIIBBUUTTIIOONN
Source code for _p_h is available by anonymous ftp to
uxc.cso.uiuc.edu, _i_n _t_h_e _f_i_l_e _p_u_b/_p_h._t_a_r._Z. The complete
system, including source for the _q_i(8) server side is in the
file pub/qi.tar.Z. This source works on 4.[23]BSD UNIX sys-
tems. Any troubles encountered porting _p_h to a particular
system are of interest to the maintainer of _p_h, as are ports
done to other operating systems.
SSEEEE AALLSSOO
_T_h_e _C_C_S_O _N_a_m_e_s_e_r_v_e_r - _A_n _I_n_t_r_o_d_u_c_t_i_o_n, by Steven Dorner;
updated by Paul Pomes.
_T_h_e _C_C_S_O _N_a_m_e_s_e_r_v_e_r - _S_e_r_v_e_r-_C_l_i_e_n_t _P_r_o_t_o_c_o_l, by Steven
Dorner; updated by Paul Pomes.
_q_i(8)
AAUUTTHHOORR
Steve Dorner (
[email protected]), Qualcomm, Inc. (form-
erly at the University of Illinois Computing and Communica-
tions Services Office)
The code is now maintained by Paul Pomes (
[email protected]),
University of Illinois Computing and Communications Services
Office.
Printed 8/30/92 30-Jul-1992 8
