








      A Tour Through the C News Libraries and Include
                           Files


                       Geoff Collyer

                  Department of Statistics
                   University of Toronto





_l_i_b_c _a_n_d _f_r_i_e_n_d_s

_l_i_b_c contains routines that are sufficiently useful and gen-
eral that they could profitably be added to one's C library.
Indeed, on some systems they are in the C library.   Notable
inventions  include  _f_g_e_t_m_f_s which safely reads arbitrarily-
long input lines; it has an _f_g_e_t_m_f_s._h  over  in  the  header
directories.  _l_d_i_v is the ANSI one, if you need it.  _m_e_m_l_i_s_t
is a package to ease keeping track of  a  lot  of  allocated
memory.   _s_t_d_f_d_o_p_e_n  is invoked by setuid programs to ensure
that the standard file descriptors are indeed open,  opening
/_d_e_v/_n_u_l_l on each closed standard descriptor.

_l_i_b_s_t_d_i_o contains new (faster) guts for the  original  UNIX|-
_s_t_d_i_o  library;  if  they compile on your V7, 4BSD or System
III system, you may want to use them instead of the  default
versions in your C library.  On System V, these routines are
only slightly faster than the versions in the C library.

_l_i_b_f_a_k_e contains things that probably should be  in  your  C
library, but might not be, and a couple of fake routines for
system calls you might not have.

_l_i_b_c_n_e_w_s

_l_i_b_c_n_e_w_s contains functions of general use to news software,
but  not  the world at large.  _c_o_m_p_l_a_i_n is like _w_a_r_n_i_n_g, but
never prints the symbolic value of _e_r_r_n_o.

     There  is  a  locking  package,  containing  _l_o_c_k_d_e_b_u_g,
_n_e_w_s_l_o_c_k,  _n_e_w_s_u_n_l_o_c_k,  _e_r_r_u_n_l_o_c_k,  and _n_e_m_a_l_l_o_c.  _l_o_c_k_d_e_b_u_g
enables or disables lock debugging.   _n_e_w_s_l_o_c_k  attempts  to
lock the news transport layer against read-then-write access
to the _a_c_t_i_v_e file, writing to the  _h_i_s_t_o_r_y*,  _l_o_g,  _e_r_r_l_o_g,
and  batch  files.  It returns only when it has the lock; in
_________________________
|- UNIX is a trademark of Bell Laboratories.




                       March 26, 1991





                           - 2 -


the meantime it sleeps and retries until it gets  the  lock.
There  is no timeout; this is a feature.  _n_e_w_s_u_n_l_o_c_k removes
the above-mentioned lock if this  process  locked  the  news
system.   _e_r_r_u_n_l_o_c_k is like _e_r_r_o_r except that it unlocks the
news system (via _n_e_w_s_u_n_l_o_c_k) before exiting;  it  is  should
always  be  called instead of _e_x_i_t(3) or _e_x_i_t(2) if there is
any chance that this process has  locked  the  news  system.
_n_e_m_a_l_l_o_c  is like _e_m_a_l_l_o_c but it calls _e_r_r_u_n_l_o_c_k if it can't
allocate memory.

     _l_t_o_z_a converts a _l_o_n_g _i_n_t to a string of a given width,
containing   the  decimal  representation,  zero-padding  as
needed on the left.  _l_t_o_z_a_n is like _l_t_o_z_a but omits the ter-
minating  NUL,  so  it  can  be  used  to overwrite a string
without  truncating  it.   _n_g_m_a_t_c_h  returns  a   truth-value
resulting  from comparing a list of newsgroup patterns and a
list of newsgroups.  One may substitute ``distribution'' for
``newsgroup''.

     There is a package of pathname  manipulators.   _a_r_t_f_i_l_e
returns  a  name  for  its  filename argument, assumed to be
relative to $_N_E_W_S_A_R_T_S;  _f_u_l_l_a_r_t_f_i_l_e  promises  to  return  a
fully-qualified  path  name.  _c_t_l_f_i_l_e returns a name for its
filename argument, assumed to be relative to $_N_E_W_S_C_T_L.  _b_i_n_-
_f_i_l_e returns a name for its filename argument, assumed to be
relative to $_N_E_W_S_B_I_N.  _c_d changes to its argument directory,
check  for errors, and notes the directory name, by making a
private copy, for later  optimisations.   _n_e_w_s_u_m_a_s_k  returns
the  value  of  $_N_E_W_S_U_M_A_S_K.   _n_e_w_s_p_a_t_h  returns the value of
$_N_E_W_S_P_A_T_H.  _n_e_w_s_m_a_s_t_e_r returns  the  value  of  $_N_E_W_S_M_A_S_T_E_R.
All  these  functions  supply  default  values for the _N_E_W_S*
variables if none are found in the environment.   If  values
are  found in the environment, they are used, and a function
named _u_n_p_r_i_v_i_l_e_g_e_d is called.

     _r_e_a_d_l_i_n_e is like  _f_g_e_t_s,  but  executes  _n_e_w_s_l_o_c_k  upon
encountering  EOF  and  retries the read.  This is used when
reading growing  files  such  as  _h_i_s_t_o_r_y  or  batch  files.
_s_t_r_l_o_w_e_r  down-cases an entire string, in place.  _s_t_r_s_a_v_e is
like _s_t_r_d_u_p but  it  calls  _n_e_m_a_l_l_o_c  rather  than  _e_m_a_l_l_o_c.
_s_t_r_3_s_a_v_e takes three strings, allocates space for their con-
catenation via _n_e_m_a_l_l_o_c, including terminating NUL, and con-
catenates them onto it.  A _N_U_L_L argument will be replaced by
an empty string.  _t_i_m_e_s_t_a_m_p writes a timestamp  on  a  given
stream,  and  returns  the  current time via an argument for
later use.

_U_n_i_x-_v_a_r_i_a_n_t-_s_p_e_c_i_f_i_c _l_i_b_r_a_r_i_e_s

There are several libraries that provide functions for talk-
ing  to  specific  Unix variants.  These are basically func-
tions that change from one variant to another.  _l_i_b_f_a_k_e (see
above)  contains things which simply might not be there in a
particular system.



                       March 26, 1991





                           - 3 -


These libraries all provide the same  virtual  interface  to
operating-system-dependent  services:  _f_c_l_s_e_x_e_c,  _f_o_p_e_n_e_x_c_l,
_g_e_t_c_w_d(3), and _g_e_t_h_o_s_t_n_a_m_e(3).  Implementations for  vanilla
implementations of these UNIX variants are provided: Seventh
Edition, including 4.1BSD (_l_i_b_v_7); Eighth and Ninth Editions
(_l_i_b_v_8);  4.2BSD and later (_l_i_b_b_s_d_4_2); System III and System
V (_l_i_b_u_s_g).  _f_c_l_s_e_x_e_c sets  the  close-on-exec  flag  for  a
given  _s_t_d_i_o  stream.   _f_o_p_e_n_e_x_c_l  performs  an  ``exclusive
create'' open: the open fails if the file already exists.

_A_d_d_r_e_s_s-_s_p_a_c_e-_s_i_z_e-_s_p_e_c_i_f_i_c _l_i_b_r_a_r_i_e_s

These libraries provide alternate versions of the _a_c_t_i_v_e and
_s_y_s  file  code: _l_i_b_s_m_a_l_l should work on any machine, but is
suboptimally fast; _l_i_b_b_i_g has worked even on PDP-11s, and is
quite fast, but consumes memory without apology.

_I_n_c_l_u_d_e _f_i_l_e_s

_l_i_b_h contains  include  files  unique  to  C  news.   _n_e_w_s._h
defines  a  few limits, some file names, some types (_b_o_o_l_e_a_n
and _s_t_a_t_u_s_t), some characters, some status bits, some macros
for speed, and declares functions in _l_i_b_c_n_e_w_s or miscellane-
ous functions in _r_e_l_a_y_n_e_w_s (oops!).  _c_o_n_f_i_g._h  declares  the
pathname functions in _l_i_b_c_n_e_w_s.  _f_g_e_t_m_f_s._h declares symbolic
values and macros for using _f_g_e_t_m_f_s.  _l_i_b_c._h is a start at a
V9-like  declaration  of  all  of  the C library.  _m_e_m_l_i_s_t._h
defines the interface to _m_e_m_l_i_s_t.

_h_f_a_k_e contains a few include files that your system ought to
have but might not.  _s_t_d_l_i_b._h is a degenerate ANSI _s_t_d_l_i_b._h.
_s_t_r_i_n_g._h declares the string  functions.   _t_i_m_e_b._h  declares
the structure used by _f_t_i_m_e.
























                       March 26, 1991


