libinn man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

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(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
       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
       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 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, 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 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 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 From‐
       Server and ToServer parameters should be FILE's connected to  the  NNTP
       server  for input and output, respectively.  See NNTPremoteopen or NNT‐
       Plocalopen, 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 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.

       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  con‐
       nected  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; other‐
       wise it calls times(2).	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) if <$ac_cv_func_gettimeofday in con‐
       fig.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 call‐
       ing 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 connection, 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 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  pro‐
       gram  can  use this routine.  It returns -1 on failure, or zero on suc‐
       cess.

       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 fail‐
       ure, 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 1.15, dated 2003/01/14.

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 SuSE

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