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: p-pomes@uiuc.edu (paul@uxc.cso.uiuc.edu) 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 (sdorner@qualcomm.com), Qualcomm, Inc. (form- erly at the University of Illinois Computing and Communica- tions Services Office) The code is now maintained by Paul Pomes (p-pomes@uiuc.edu), University of Illinois Computing and Communications Services Office. Printed 8/30/92 30-Jul-1992 8