LIBINN(3)

LIBINN(3)

libexpect Home Page Subroutines Index libpbm


NAME
       libinn - InterNetNews library routines

SYNOPSIS
       #include "libinn.h"

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

       char *
       GenerateMessageID()

       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;

       void

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

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

       int
       LockFile(fd, flag)
           int              fd;
           int              flag;

       char *
       GetConfigValue(value)
           char             *value;

       char *
       GetFileConfigValue(value)
           char             *value;

       char *
       GetFQDN()

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

       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(FromServerp, ToServerp, errbuff)
           FILE             **FromServerp;
           FILE             **ToServerp;
           char             *errbuff;

       int
       NNTPconnect(host, FromServerp, ToServerp, errbuff)

           char             *host;
           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()

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 of the local host to create  a
       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
       proper value for the Distribution header after  all  news-
       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.

       LockFile tries to lock the file descriptor fd.  If flag is
       non-zero  it will block until the lock can be made, other-
       wise it will return -1 if the file cannot be  locked.   It
       returns -1 on failure or zero on success.

       GetConfigValue returns the value of the specified configu-
       ration parameter.  See  inn.conf(5)  for  details  on  the
       parameters  and  their interpretation.  The returned value
       points to static space that is reused on subsequent calls.

       GetFileConfigValue  returns  the  specified  configuration
       parameter from the inn.conf file without checking for  any
       defaults.   The returned value points to static space that
       is reused on subsequent calls, or NULL if the value is not
       present.

       GetFQDN  returns  the  fully-qualified  domain name of the
       local host.  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.  See  mod-
       erators(5)  for  details on how the address is determined.
       GetModeratorAddress does no checking to see if the  speci-
       fied  group  is  actually  moderated.   The returned value
       points to static space that is reused on subsequent calls.
       The  FromServer  and  ToServer parameters should be FILE's
       connected to the NNTP server for input and output, respec-
       tively.   If  either  of these parameters 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.   It
       gets  the  values by doing a getrusage(2) system call.  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

       gettimeofday(2).   The  ``tzone''  field will be filled in
       with the current offset from GMT.  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 GetTimeInfo  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.  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.

       NNTPremoteopen  does the same except that it calls GetCon-
       figValue to find the name of the local server, and opens a
       connection  to the standard NNTP port.  Any client program
       can use this routine.  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-
       termination marker on the stream.  It returns -1 on  fail-
       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; GetConfigValue 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.

EXAMPLES
              char             *p;
              char             *Article;
              char             buff[256];
              FILE             *F;
              FILE             *ToServer;
              FILE             *FromServer;
              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. */
              p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
              /* Close the file. */
              CAclose();
              if (NNTPremoteopen(&FromServer, &ToServer) < 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 lt;rsalz@uunet.uu.net for InterNet-
       News.  This is revision 1.21, dated 1996/07/12.

SEE ALSO
       active(5) dbz(3z) parsedate(3) inn.conf(5) innd- 
       comm(3) moderators(5) passwd.nntp(5). 

libexpect Home Page Subroutines Index libpbm