

PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


NNAAMMEE
    ph -- access to the CSO Nameserver (on-line phone book)

SSYYNNOOPPSSIISS

    pphh [--ss server] [--pp port] query
    pphh [--ss server] [--pp port] [--nn]

DDEESSCCRRIIPPTTIIOONN
    _P_h queries the CSO Nameserver, a database of University
    faculty, students and staff.  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, it will treat the arguments as a query,
    and return the results of the query.  For example,

          ph steven dorner

    would return the entry for the author of _p_h, Steven Dorner.
    For more information on what types of queries you may make,
    see the _Q_u_e_r_i_e_s 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.

OOPPTTIIOONNSS
    _P_h recognizes the following options:

        -n    Do not read the ..nneettrrcc file.  This option has
              meaning only when using _p_h in interactive mode (see
              below for descriptions of the .netrc file and
              interactive mode.)

        -s _s_e_r_v_e_r

              Use _s_e_r_v_e_r as a Nameserver host, instead of the
              default host.

        -p _p_o_r_t

              Use _p_o_r_t as the tcp port to connect to, instead of
              the default port.


Page 1                                         (printed 10/11/89)


PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


QQUUEERRIIEESS
    The Nameserver's database containes over 60,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 _m_a_i_l__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 ffiieellddss command in the _I_n_t_e_r_a_c_t_i_v_e
    section below).

    By default, queries are assumed to refer to the _n_a_m_e field of
    the entry.  Therefore, saying ''pphh jjoohhnn ddooee'' looks for
    entries whose name field contains ''john'' and ''doe.''
    Fields other than the _n_a_m_e field must be specified; for
    example,

          ph dorner address=DCL

    would return entries with name ''dorner'' whose address
    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
    insensitive to case, it otherwise requires words to match
    exactly, with no characters left over; ''john'' does nnoott
    match ''johnson,'' 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 aallll of the
    specifications in the query.  For example,

          ph steven dorner

    will return all entries with bbootthh ''steven'' and ''dorner''
    in the _n_a_m_e field.

    _P_h returns a certain set of fields by default.  It is
    possible 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 steven dorner return email

    would print only the electronic mail address of the author 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 user's entry.


Page 2                                         (printed 10/11/89)


PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


    All output from _p_h is sent through _m_o_r_e (or whatever program
    specified in the _P_A_G_E_R environment variable).

IINNTTEERRAACCTTIIVVEE MMOODDEE
    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 _l_o_g_i_n command; others do not.  Commands may be
    abbreviated, provided enough characters are given to
    distinguish them from other commands.

    TThhee ..nneettrrcc ffiillee
    _P_h reads the same .netrc file as does ftp (see ftp(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_hwill automatically do a _l_o_g_i_n
    command, using the values from the .netrc file.  _P_h will
    silently refuse to use a .netrc file that has any permissions
    for group or other (see chmod(1)).

    PPuubblliicc CCoommmmaannddss
    The following commands do not require the user to be logged
    in to the Nameserver:

    hheellpp
    _H_e_l_p provides explanations of Nameserver commands.  Given no
    arguments, _h_e_l_p lists the available help topics.  Given one
    of these topics as an argument, _h_e_l_p 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.

    qquueerryy
    _Q_u_e_r_y performs Nameserver queries, and works exactly like
    non-interactive _p_h, except that metacharacters do not have to
    be quoted.

    ffiieellddss
    _F_i_e_l_d_s 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 Turn
    -200:2:email:Preferred electronic mail address.

    The leading number is a reply code form 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 flags for the field.  The second line has, in
    addition to repeated reply code, number, and name, a one-line
    description of the field.


Page 3                                         (printed 10/11/89)


PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


    The flags 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.  _T_u_r_n
    means that display of the field may be inhibited by beginning
    the field with a ''*''.

    sseett option[==value]
    _S_e_t allows Nameserver options to be set.  These options are
    for future use.

    qquuiitt
    Exits _p_h.

    llooggiinn alias
    This command 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 the first field printed in _p_h queries.  You
    will be prompted for your Nameserver password.  This is nnoott
    the same as your system password.  The only way to discover
    your Nameserver password is to send mail to
    nameserv@uxg.cso.uiuc.edu.

    You are allowed to change your Nameserver alias; there are,
    however, restrictions on Nameserver alia; they must be unique
    within the Nameserver, they cannot be common names (''david''
    is right out), and they can only contain letters, digits,
    dashes (-) and periods (.).

    CCoommmmaannddss RReeqquuiirriinngg LLooggiinn
    The following commands require that the user executing them
    be logged in to the Nameserver.

    ppaasssswwoorrdd [alias]
    This command 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 passwords).  Privileged users
    may change the passwords of certain other users by specifying
    the alias of the other user when giving the _p_a_s_s_w_o_r_d command.

    mmee
    This command lists the nameserver entry of the currently
    logged-in user.

    eeddiitt field [alias]
    This command allows _p_h users to change those fields in their
    entry that have the _C_h_a_n_g_e flag 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 /_u_s_r/_u_c_b/_v_i (the _E_D_I_T_O_R
    environment variable may be used to override the use of _v_i).


Page 4                                         (printed 10/11/89)


PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


    The changed value will then be reinserted in the Nameserver.

    aadddd
    Adds entries to the Nameserver.  This is a privileged
    command.

    ddeelleettee
    Deletes entries from the Nameserver.  This is a privileged
    command.

    llooggoouutt
    Undoes the effects of a _l_o_g_i_n command.

QQUUEERRYY EEXXAAMMPPLLEESS
    Here are some examples to clarify _p_h queries.  Each example
    is preceded by the effect desired.  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 metacharacters would
    not have to be quoted or escaped.

    Find the _p_h entry for Steven Dorner:

          ph steven dorner

    Find the ph entry for S. Dorner, where the rest of the first
    name is not known:

          ph s\* dorner

    Find Alonzo Johnson (or is that JohnsEn?):

          ph alonzo johns\?n
    or
          ph alonzo johns\[eo\]n

    Find Steven D., where the rest of the last name is unknown:

          ph steven d\*

    The last query fails because it matches too many entries.  It
    is therefore necessary to narrow the search.  Suppose is is
    known that Steven D. has an office in DCL:

          ph steven d\* address=DCL

    Alternately, suppose Steven D. works for CSO.  You might try:

          ph steven d\* department=CSO

    When that failed, a good next guess would be:


Page 5                                         (printed 10/11/89)


PH(1L)              UNIX 4.3 BSD (27 Aug 89)               PH(1L)


          ph steven d\* department=computing

    The moral of the story is that fields in _p_h generally contain
    whatever the user wishes them to contain, and hence there may
    be many different spellings and abbreviations of 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 full name and electronic mail
    address of S. Dorner:

          ph s\* dorner return name email

BBUUGGSS
    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.''

    There is no way to turn off the reading of the .netrc file.

DDIISSTTRRIIBBUUTTIIOONN
    Source code for _p_h is available by anonymous ftp to
    uxc.cso.uiuc.edu, in the net/ph subdirectory.  This source
    works on 4.[23]bsd Unix systems.  Any troubles encountered
    porting _p_h to a particular system are of interest to the
    author of _p_h, as are ports done to other operating systems.

SSEEEE AALLSSOO
    _T_h_e _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
    _T_h_e _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
    qi(8)

AAUUTTHHOORR
    Steve Dorner
    University of Illinois Computing Services Office
    s-dorner@uiuc.edu


Page 6                                         (printed 10/11/89)


Page 7                                         (printed 10/11/89)