libinn man page on 4.4BSD

Printed from http://www.polarhome.com/service/man/?qf=libinn&af=0&tf=2&of=4.4BSD

LIBINN(3)							     LIBINN(3)

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(group)
	   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 arti‐
       cles and related data.  It is not necessary to use the header file lib‐
       inn.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-quali‐
       fied  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 for‐
       mat 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 contain‐
       ing  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 subse‐
       quent 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	 allo‐
       cated 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 suc‐
       cess.

       GetConfigValue returns the value of the specified configuration parame‐
       ter.  See inn.conf(5) for details on the parameters and their interpre‐
       tation.	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.

       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 cur‐
       rent 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 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.  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 stan‐
       dard 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 fail‐
       ure, or zero on success.

       NNTPsendpassword	 sends authentication information to an NNTP server by
       finding the appropriate entry in the passwd.nntp(5) file.  Server  con‐
       tains  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.20, dated 1993/01/29.

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

								     LIBINN(3)
[top]

List of man pages available for 4.4BSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net