Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBINN(3)		   Library Functions Manual		     LIBINN(3)

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 arti-
       cles and	related	data.

       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 5536 which limits the for-
       mat 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 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.

       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 af-
       ter  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 con-
       nected to the NNTP server for input and output, respectively.   If  ei-
       ther  parameter	is  NULL, then an empty	default	will ultimately	be re-
       turned 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.

       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  ad-
       dress, 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 pa-
       rameters	 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  de-
       fined,  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.

       NNTPlocalopen opens a connection	to the private port of an InterNetNews
       server  running	on the local host, if _HAVE_UNIX_DOMAIN_SOCKETS	in in-
       clude/config.h_ is defined.  It returns -1 on failure, or zero on  suc-
       cess.   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  in-
       clude/config.h_ is not defined, this is a stub routine, for compatibil-
       ity with	systems	that have Unix-domain stream sockets.  It  always  re-
       turns -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 er-
       ror.   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	10262, dated 2018-03-10.

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

								     LIBINN(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | HISTORY | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libinn&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help