libinn man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi 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()

       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

								1

LIBINN(3)						LIBINN(3)

       CloseOnExec(fd, flag)
	   int		    fd;
	   int		    flag;

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

       int
       LockFile(fd, flag)
	   int		    fd;
	   int		    flag;

       int
       ReadInnConf()

       char *
       GetFQDN()

       char *
       GetModeratorAddress(FromServer, ToServer, group)
	   FILE		    *FromServer;
	   FILE		    *ToServer;
	   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(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;

								2

LIBINN(3)						LIBINN(3)

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

								3

LIBINN(3)						LIBINN(3)

	      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 speci-
       fied 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 charac-
       ters.

       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 con-
       nected to the NNTP server for input  and	 output,  respec-
       tively.	 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  argu-
       ment  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 Distribu-
       tion 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  news-
       groups 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 parame-
       ters 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

								4

LIBINN(3)						LIBINN(3)

       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.

       LockFile tries to lock the file descriptor fd.  If flag is
       non-zero	 it will block until the lock can be made, other-
       wise it will return -1 if the file cannot be  locked.   It
       returns -1 on failure or zero 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-
       tered.

       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 mod-
       erators(5) for details on how the address  is  determined.
       GetModeratorAddress  does no checking to see if the speci-
       fied 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 parame-
       ters with the total user and system time used by the  cur-
       rent  process  and  any	children it may have spawned.  If
       <RES_STYLE in config.data> == RUSAGE, 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  gettimeof-
       day(2)  when <$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,

								5

LIBINN(3)						LIBINN(3)

       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 Get-
       TimeInfo has been called.   This	 routine  returns  -1  on
       failure, or zero on success.

       NNTPlocalopen	 when	  <HAVE_UNIX_DOMAIN_SOCKETS    in
       include/config.h> is defined, 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  con-
       nection,	 then  it  will be filled in with the text of the
       server's reply.	This routine  is  not  for  general  use.
       When <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	to find the name of 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 conven-
       tions 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  contains  the  name  of  the
       host;  innconf->server  will  be	 used  if server is NULL.
       FromServer and ToServer should be  FILE's  that	are  con-
       nected 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

								6

LIBINN(3)						LIBINN(3)

       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  mem-
       ory,  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], 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	InterNet-
       News.  This is revision 1.1.2.2, dated 2000/04/04.

								7

LIBINN(3)						LIBINN(3)

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

								8

[top]

List of man pages available for BSDi

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