Provided by: inn2-dev_2.6.3-1_amd64 bug

NAME

       libinn - InterNetNews library routines

SYNOPSIS

       #include "inn/libinn.h"

       char *
       GenerateMessageID(domain)
           char    *domain;

       void
       HeaderCleanFrom(from)
           char             *from;

       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
       fdflag_close_exec(fd, flag)
           int              fd;
           bool             flag;

       int
       fdflag_nonblocking(fd, flag)
           socket_type      fd;
           bool             flag;

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

       char *
       inn_getfqdn(domain)
           const 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.

       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.

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

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

       inn_getfqdn returns the fully qualified domain name of the local host.  Domain is used  to
       qualify  the local host name if local host can not be resolved in DNS.  The returned value
       points to newly-allocated memory that the caller is responsible for freeing,  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             frombuff[256], errbuff[256];
              FILE             *F;
              FILE             *ToServer;
              FILE             *FromServer;
              int              port = 119;

              strlcpy(frombuff, HDR(HDR__FROM), sizeof(frombuff));
              HeaderCleanFrom(frombuff);

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

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

              /* Make a local copy. */
              p = ReadInDescriptor(fileno(F), (struct stat *)NULL);

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

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

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

HISTORY

       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  This is revision 10304, dated
       2018-12-02.

SEE ALSO

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

                                                                                        LIBINN(3)