Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for libinn (redhat section 3)

LIBINN(3)			     Library Functions Manual				LIBINN(3)

NAME
       libinn - InterNetNews library routines

SYNOPSIS
       #include "libinn.h"

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

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

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

       BOOL
       lock_file(fd, type, flag)
	   int		    fd;
	   LOCKTYPE	    type;
	   BOOL 	    block;

       int
       ReadInnConf()

       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
       GetTimeInfo(now)
	   TIMEINFO	    *now;

       int
       NNTPlocalopen(FromServerp, ToServerp, errbuff)
	   FILE 	    **FromServerp;
	   FILE 	    **ToServerp;
	   char 	    *errbuff;

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

       int
       NNTPconnect(host, port, FromServerp, ToServerp, errbuff)
	   char 	    *host;
	   int		    port;
	   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()

       HASH
       HashMessageID(MessageID)
	   const char *MessageID;

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,
       which is passed as an argument and used if local host can not be resolved or it is differ-
       ent  from  ``domain''  set  in  inn.conf(5) , to create a Message-ID header that is highly
       likely to be unique.  The returned value points to static space that is reused  on  subse-
       quent 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 fol-
       lowing 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  con-
       taining	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.

       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:  LLOCK_READ, LLOCK_WRITE, or LOCK_UNLOCK.  It returns FALSE on failure or TRUE on
       success.

       ReadInnConf Reads the values of the inn.conf(5) parameters into the innconf  stucture  for
       use  as	``innconf->varname''.  The return value is less than zero if an error was encoun-
       tere or zero 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, 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 parameters with the total user and sys-
       tem 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.

       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)  if
       <$ac_cv_func_gettimeofday in config.cache> is ``yes''.  Otherwise, the ``time'' field will
       be filled in by a call to time(2), and the ``usec''  field  will  be  set  to  zero.   The
       ``tzone'' field will be filled in with the current offset from GMT.  If <HAVE_TM_GMTOFF in
       include/config.h> is defined, this is done by calling localtime(3) and taking the value of
       the  ``tm_gmtoff''  field, negating it, and dividing it by 60.  Otherwise, 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, 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 con-
       nection,  then  it will be filled in with the text of the server's reply.  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 sock-
       ets.  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.

       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 appro-
       priate entry  in  the  passwd.nntp(5)  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.

       INNVersion returns a pointer to a string identifying the INN version, suitable for  print-
       ing in logon banners.

       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 1.8.2.1,
       dated 2000/08/17.

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

											LIBINN(3)


All times are GMT -4. The time now is 11:20 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password