Provided by: inn_1.7.2debian-30_i386 bug

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 specified 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
       containing the text of the article; the end of the headers is indicated
       by a blank line — two consecutive \n characters.

       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  connected  to  the
       NNTP  server for input and output, respectively.  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 argument 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 Distribution 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 newsgroups 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  parameters  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, otherwise 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  configuration
       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 moderators(5) for details on how
       the address is determined.  GetModeratorAddress does no checking 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 parameters should be FILE’s  connected  to  the
       NNTP  server  for  input  and output, respectively.  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 parameters with the
       total user and system time used by the current 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 taking the value of the ‘‘tm_gmtoff’’ field,  negating
       it, and dividing it by 60.  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  GetConfigValue  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 conventions 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
       failure, 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  connected  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 memory, 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 <rsalz@uunet.uu.net> for  InterNetNews.   This  is
       revision 1.21, dated 1996/07/12.

SEE ALSO

       active(5),    dbz(3z),    parsedate(3),    inn.conf(5),    inndcomm(3),
       moderators(5), passwd.nntp(5).

                                                                     LIBINN(3)