Provided by: inn_1.7.2q-46_amd64 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)