Provided by: inn2-dev_2.5.2+20110413-1_i386 bug

NAME

       libinn - InterNetNews library routines

SYNOPSIS

       #include "inn/libinn.h"

       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;

       void
       close_on_exec(fd, flag)
           int              fd;
           bool             flag;

       int
       nonblocking(fd, flag)
           int              fd;
           bool             flag;

       bool
       inn_lock_file(fd, type, flag)
           int              fd;
           LOCKTYPE         type;
           bool             block;

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

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

       int
       NNTPconnect(host, port, FromServerp, ToServerp, errbuff, len)
           char             *host;
           int              port;
           FILE             **FromServerp;
           FILE             **ToServerp;
           char             *errbuff;
           size_t  len;

       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;

       HASH
       HashMessageID(MessageID)
           const char *MessageID;

DESCRIPTION

       Libinn  is  a  library  of  utility  routines  for  manipulating Usenet
       articles and related data.

       GenerateMessageID  uses  the  current  time,  process-ID,  and   fully-
       qualified domain name, which is passed as an argument and used if local
       host can not be resolved or it is  different  from  ``domain''  set  in
       inn.conf,  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 5536  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 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  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.

       inn_lock_file tries to lock the file descriptor fd.  If block  is  true
       it  will  block  until  the  lock can be made, otherwise it will return
       false if the file cannot be locked.  type  is  one  of:  INN_LOCK_READ,
       INN_LOCK_WRITE,  or  INN_LOCK_UNLOCK.   It  returns false on failure or
       true 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.   Moderatormailer  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
       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.   If  <HAVE_GETRUSAGE  in  include/config.h>  is
       defined,  it  gets  the  values  by  doing  a getrusage(2) system call;
       otherwise it calls times(2).  It 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.  Len should be the length of the  buffer.   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  connection to the 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.

       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 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 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.

       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. */
              p = ReadInDescriptor(fileno(F), (struct stat *)NULL);

              /* 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  InterNetNews.   This  is
       revision 8894, dated 2010-01-17.

SEE ALSO

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

                                                                     LIBINN(3)