libinn - InterNetNews library routines


SYNOPSIS

       #include "libinn.h"

       typedef struct _TIMEINFO {
           time_t           time;
           long             usec;
           long             tzone;
       } TIMEINFO;

       char *
       GenerateMessageID(domain)
           char    *domain;

       void
       HeaderCleanFrom(from)
           char             *from;

       char *
       HeaderFind(Article, Header, size)
           char             *Article;
           char             *Header;
           int              size;

       FILE *
       CAopen(FromServer, ToServer)
           FILE             *FromServer;
           FILE             *ToServer;

       FILE *
       CAlistopen(FromServer, ToServer, request)
           FILE             *FromServer;
           FILE             *ToServer;
           char             *request;

       void
       CAclose()

       struct _DDHANDLE *
       DDstart(FromServer, ToServer)
           FILE             *FromServer;
           FILE             *ToServer;

       void
       DDcheck(h, group)
           DDHANDLE         *h;
           char             *group;

       char *
       DDend(h)
           DDHANDLE         *h;

       CloseOnExec(fd, flag)
           int              fd;
           int              flag;

       int
       SetNonBlocking(fd, flag)
           int              fd;
           int              flag;

       BOOL
       lock_file(fd, type, flag)
           int              fd;
           LOCKTYPE         type;
           BOOL             block;

       int
       ReadInnConf()

       char *
       GetFQDN(domain)
           char    *domain;

       char *
       GetModeratorAddress(FromServer, ToServer, group, moderatormailer)
           FILE             *FromServer;
           FILE             *ToServer;
           char             *group;
           char             *moderatormailer;

       int
       GetResourceUsage(usertime, systime)
           double           *usertime;
           double           *systime;

       int
       GetTimeInfo(now)
           TIMEINFO         *now;

       int
       NNTPlocalopen(FromServerp, ToServerp, errbuff)
           FILE             **FromServerp;
           FILE             **ToServerp;
           char             *errbuff;

       int
       NNTPremoteopen(port, FromServerp, ToServerp, errbuff)
           int              port;
           FILE             **FromServerp;
           FILE             **ToServerp;
           char             *errbuff;

       int
       NNTPconnect(host, port, FromServerp, ToServerp, errbuff)

           int              port;
           FILE             **FromServerp;
           FILE             **ToServerp;
           char             *errbuff;

       int
       NNTPcheckarticle(text)
           char             *text;

       int
       NNTPsendarticle(text, ToServer, Terminate)
           char             *text;
           FILE             *ToServer;
           int              Terminate;

       int
       NNTPsendpassword(server, FromServer, ToServer)
           char             *server;
           FILE             *FromServer;
           FILE             *ToServer;

       void
       Radix32(value, p)
           unsigned long    value;
           char             *p;

       char *
       ReadInFile(name, Sbp)
           char             *name;
           struct stat      *Sbp;

       char *
       ReadInDescriptor(fd, Sbp)
           int              fd;
           struct stat      *Sbp;

       char *
       INNVersion()

       HASH
       HashMessageID(MessageID)
           const char *MessageID;


DESCRIPTION

       Libinn  is  a library of utility routines for manipulating
       Usenet articles and related data.  It is not necessary  to
       use  the  header file libinn.h; if it is not available, it
       is  only  necessary  to  properly  declare  the   TIMEINFO
       datatype, as given above.

       GenerateMessageID  uses  the current time, process-ID, and
       fully-qualified domain name, which is passed as  an  argu­
       ment  and  used if local host can not be resolved or it is

       Message-ID header that is highly likely to be unique.  The
       returned value points to static space that  is  reused  on
       subsequent calls.

       HeaderCleanFrom  removes  the  extraneous information from
       the value of a ``From'' or ``Reply-To'' header and  leaves
       just  the  official  mailing  address.  In particular, the
       following transformations are made to the from parameter:
              address          -->  address
              address (stuff)  -->  address
              stuff <address>  -->  address
       The transformations are simple, based  on  RFC 1036  which
       limits the format of the header.

       HeaderFind searches through Article looking for the speci­
       fied Header.  Size should be  the  length  of  the  header
       name.   It  returns  a pointer to the value of the header,
       skipping leading whitespace, or NULL if the header  cannot
       be  found.  Article should be a standard C string contain­
       ing the text of the article; the end  of  the  headers  is
       indicated  by  a  blank line -- two consecutive \n charac­
       ters.

       CAopen and CAclose provide news clients with access to the
       active  file; the ``CA'' stands for Client Active.  CAopen
       opens the  active(5)  file  for  reading.   It  returns  a
       pointer  to an open FILE, or NULL on error.  If a local or
       NFS-mounted copy exists, CAopen will use that  file.   The
       FromServer  and  ToServer parameters should be FILE's con­
       nected to the NNTP server for input  and  output,  respec­
       tively.   See  NNTPremoteopen or NNTPlocalopen, below.  If
       either parameter is NULL, then  CAopen  will  just  return
       NULL  if  the  file is not locally available.  If they are
       not NULL, CAopen will use them to query  the  NNTP  server
       using the ``list'' command to make a local temporary copy.

       The CAlistopen sends a ``list'' command to the server  and
       returns  a  temporary  file  containing  the results.  The
       request parameter, if not NULL, will be sent as  an  argu­
       ment  to  the  command.   Unlike CAopen, this routine will
       never use a locally-available copy of the active file.

       CAclose closes the active file and removes  any  temporary
       file that might have been created by CAopen or CAlistopen.

       CloseOnExec can make  a  descriptor  ``close-on-exec''  so
       that  it  is  not shared with any child processes.  If the
       flag is non-zero, the file is  so  marked;  if  zero,  the
       ``close-on-exec'' mode is cleared.

       DDstart,  DDcheck, and DDend are used to set the Distribu­
       tion header; the ``DD'' stands for  Default  Distribution.
       The  distrib.pats(5)  file  is  consulted to determine the

       groups have been checked.  DDstart begins the parsing.  It
       returns a pointer to an opaque handle that should be  used
       on  subsequent calls.  The FromServer and ToServer parame­
       ters should be FILE's connected to  the  NNTP  server  for
       input  and  output,  respectively.  If either parameter is
       NULL, then an empty default will ultimately be returned if
       the file is not locally available.

       DDcheck  should  be called with the handle, h, returned by
       DDstart and a newgroups,  group,  to  check.   It  can  be
       called as often as necessary.

       DDend  releases  any  state  maintained  in the handle and
       returns an allocated copy of the text that should be  used
       for the Distribution header.

       SetNonBlocking  enables  (if flag is non-zero) or disables
       (if flag  is  zero)  non-blocking  I/O  on  the  indicated
       descriptor.   It returns -1 on failure or zero on success.

       lock_file tries to lock the file descriptor fd.  If  block
       is  TRUE  it will block until the lock can be made, other­
       wise it will return FALSE if the file  cannot  be  locked.
       type is one of: LOCK_READ, LOCK_WRITE, or LOCK_UNLOCK.  It
       returns FALSE on failure or TRUE on success.

       ReadInnConf Reads the values of the inn.conf(5) parameters
       into the innconf stucture for use as ``innconf->varname''.
       The return value is less than zero if an error was encoun­
       tere or zero on success.

       GetFQDN  returns  the  fully-qualified  domain name of the
       local host.  Domain is used  if  local  host  can  not  be
       resolved.   The returned value points to static space that
       is reused on subsequent calls, or NULL on error.

       GetModeratorAddress returns the  mailing  address  of  the
       moderator  for  specified group or NULL on error.  Modera­
       tormailer is used as its address, if there is  no  matched
       moderator.   See  moderators(5)  for  details  on  how the
       address is determined.  GetModeratorAddress does no check­
       ing  to  see if the specified group is actually moderated.
       The returned value points to static space that  is  reused
       on  subsequent calls.  The FromServer and ToServer parame­
       ters should be FILE's connected to  the  NNTP  server  for
       input and output, respectively.  If either of these param­
       eters is NULL, then an attempt to  get  the  list  from  a
       local copy is made.

       GetResourceUsage fills in the usertime and systime parame­
       ters with the total user and system time used by the  cur­
       rent  process  and  any  children it may have spawned.  If
       <HAVE_GETRUSAGE in include/config.h> is defined,  it  gets

       it calls times(2).  It returns -1 on failure, or  zero  on
       success.

       GetTimeInfo  fills  in  the now parameter with information
       about the  current  time  and  tzone.   The  ``time''  and
       ``usec''  fields will be filled in by a call to gettimeof­
       day(2) if <$ac_cv_func_gettimeofday  in  config.cache>  is
       ``yes''.   Otherwise, the ``time'' field will be filled in
       by a call to time(2), and the ``usec'' field will  be  set
       to  zero.   The ``tzone'' field will be filled in with the
       current  offset   from   GMT.    If   <HAVE_TM_GMTOFF   in
       include/config.h>  is  defined,  this  is  done by calling
       localtime(3) and taking the  value  of  the  ``tm_gmtoff''
       field,  negating  it,  and  dividing it by 60.  Otherwise,
       this is done by calling  localtime(3)  and  comparing  the
       value with that returned by a call to gmtime(3).

       For  efficiency,  the ``tzone'' field is only recalculated
       if more than an hour pass passed since the last time  Get­
       TimeInfo  has  been  called.   This  routine returns -1 on
       failure, or zero on success.

       NNTPlocalopen opens a connection to the private port of an
       InterNetNews   server   running  on  the  local  host,  if
       <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h> is defined.
       It returns -1 on failure, or zero on success.  FromServerp
       and ToServerp will be filled in with FILE's which  can  be
       used  to  communicate with the server.  Errbuff can either
       be NULL or a pointer to a buffer at least 512 bytes  long.
       If  not  NULL, and the server refuses the connection, then
       it will be filled in with the text of the server's  reply.
       This    routine    is    not    for   general   use.    If
       <HAVE_UNIX_DOMAIN_SOCKETS  in  include/config.h>  is   not
       defined,  this  is  a stub routine, for compatibility with
       systems that have Unix-domain stream sockets.   It  always
       returns -1.

       NNTPremoteopen   does   the   same  except  that  it  uses
       ``innconf->server'' as the local server, and opens a  con­
       nection to the port.  Any client program can use this rou­
       tine.  It returns -1 on failure, or zero on success.

       NNTPconnect is the same as NNTPremoteopen except that  the
       desired host is given as the host parameter.

       NNTPcheckarticle  verifies  that  the  text meets the NNTP
       limitations on line length.  It returns -1 on failure,  or
       zero if the text is valid.

       NNTPsendarticle writes text on ToServer using NNTP conven­
       tions for line termination.  The text  should  consist  of
       one  or more lines ending with a newline.  If Terminate is
       non-zero, then the routine will also write the NNTP  data-

       ure, or zero on success.

       NNTPsendpassword sends authentication  information  to  an
       NNTP  server  by  finding  the  appropriate  entry  in the
       passwd.nntp(5) file.  Server  contains  the  name  of  the
       host;  ``innconf->server'' will be used if server is NULL.
       FromServer and ToServer should be  FILE's  that  are  con­
       nected to the server.  No action is taken if the specified
       host is not listed in the password file.

       Radix32 converts the  number  in  value  into  a  radix-32
       string  into  the  buffer  pointed to by p.  The number is
       split into five-bit pieces and each  pieces  is  converted
       into  a character using the alphabet 0..9a..v to represent
       the numbers 0..32.  Only the lowest 32 bits of  value  are
       used,  so  p  need  only  point to a buffer of eight bytes
       (seven characters and the trailing \0).

       ReadInFile reads the file named name into  allocated  mem­
       ory,  appending  a  terminating  \0  byte.   It  returns a
       pointer to the space, or NULL on error.   If  Sbp  is  not
       NULL,  it  is taken as the address of a place to store the
       results of a stat(2) call.

       ReadInDescriptor performs the same function as  ReadInFile
       except that fd refers to an already-open file.

       INNVersion  returns  a pointer to a string identifying the
       INN version, suitable for printing in logon banners.

       HashMessageID returns hashed message-id using MD5.


EXAMPLES

              char             *p;
              char             *Article;
              char             buff[256], errbuff[256];
              FILE             *F;
              FILE             *ToServer;
              FILE             *FromServer;
              int              port = 119;

              if ((p = HeaderFind(Article, "From", 4)) == NULL)
                  Fatal("Can't find From line");
              (void)strcpy(buff, p);
              HeaderCleanFrom(buff);

              if ((F = CAopen(FromServer, ToServer)) == NULL)
                  Fatal("Can't open active file");

              /* Don't pass the file on to our children. */
              CloseOnExec(fileno(F), 1);

              /* Make a local copy. */


              /* Close the file. */
              CAclose();

              if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff) < 0)
                  Fatal("Can't connect to server");

              if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
                  Fatal("Can't find moderator's address");


HISTORY

       Written by Rich $alz  <rsalz@uunet.uu.net>  for  InterNet­
       News.  This is revision 1.8.2.1, dated 2000/08/17.


SEE ALSO

       active(5),   dbz(3z),   parsedate(3),  inn.conf(5),  innd­
       comm(3), moderators(5), passwd.nntp(5).


Man(1) output converted with man2html