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

FreeBSD Manual Pages

  
 
  

home | help
qio(3)			  InterNetNews Documentation			qio(3)

NAME
       qio - Quick I/O routines	for reading files

SYNOPSIS
	   #include <inn/qio.h>

	   QIOSTATE *QIOopen(const char	*name);

	   QIOSTATE *QIOfdopen(int> I<fd);

	   void	QIOclose(QIOSTATE *qp);

	   char	*QIOread(QIOSTATE *qp);

	   int QIOfileno(QIOSTATE *qp);

	   size_t QIOlength(QIOSTATE *qp);

	   int QIOrewind(QIOSTATE *qp);

	   off_t QIOtell(QIOSTATE *qp);

	   bool	QIOerror(QIOSTATE *qp);

	   bool	QIOtoolong(QIOSTATE *qp);

DESCRIPTION
       The routines described in this manual page are part of libinn(3).  They
       are used	to provide quick read access to	files; the QIO routines	use
       buffering adapted to the	block size of the device, similar to stdio,
       but with	a more convenient syntax for reading newline-terminated	lines.
       QIO is short for	"Quick I/O" (a bit of a	misnomer, as QIO provides
       read-only access	to files only).

       The QIOSTATE structure returned by QIOopen and QIOfdopen	is the analog
       to stdio's FILE structure and should be treated as a black box by all
       users of	these routines.	 Only the above	API should be used.

       QIOopen opens the given file for	reading.  For regular files, if	your
       system provides that information	and the	size is	reasonable, QIO	will
       use the block size of the underlying file system	as its buffer size;
       otherwise, it will default to a buffer of 8 KB.	Returns	a pointer to
       use for subsequent calls, or NULL on error.  QIOfdopen performs the
       same operation except on	an already-open	file descriptor	(fd must
       designate a file	open for reading).

       QIOclose	closes the open	file and releases any resources	used by	the
       QIOSTATE	structure.  The	QIOSTATE pointer should	not be used again
       after it	has been passed	to this	function.

       QIOread reads the next newline-terminated line in the file and returns
       a pointer to it,	with the trailing newline replaced by nul.  The
       returned	pointer	is a pointer into a buffer in the QIOSTATE object and
       therefore will remain valid until QIOclose is called on that object.
       If EOF is reached, an error occurs, or if the line is longer than the
       buffer size, NULL is returned instead.  To distinguish between the
       error cases, use	QIOerror and QIOtoolong.

       QIOfileno returns the descriptor	of the open file.

       QIOlength returns the length in bytes of	the last line returned by
       QIOread.	 Its return value is only defined after	a successful call to
       QIOread.

       QIOrewind sets the read pointer back to the beginning of	the file and
       reads the first block of	the file in anticipation of future reads.  It
       returns 0 if successful and -1 on error.

       QIOtell returns the current value of the	read pointer (the lseek(2)
       offset at which the next	line will start).

       QIOerror	returns	true if	there was an error in the last call to
       QIOread,	false otherwise.  QIOtoolong returns true if there was an
       error and the error was that the	line was too long.  If QIOread returns
       NULL, these functions should be called to determine what	happened.  If
       QIOread returned	NULL and QIOerror is false, EOF	was reached.  Note
       that if QIOtoolong returns true,	the next call to QIOread will try to
       read the	remainder of the line and will likely return a partial line;
       users of	this library should in general treat long lines	as fatal
       errors.

EXAMPLES
       This block of code opens	/etc/motd and reads it a line at a time,
       printing	out each line preceded by its offset in	the file.

	   QIOSTATE *qp;
	   off_t offset;
	   char	*p;

	   qp =	QIOopen("/etc/motd");
	   if (qp == NULL) {
	       perror("Open error");
	       exit(1);
	   }
	   for (p = QIOread(qp); p != NULL; p =	QIOread(qp))
	       printf("%ld: %s\n", (unsigned long) QIOtell(qp),	p);
	   if (QIOerror(qp)) {
	       perror("Read error");
	       exit(1);
	   }
	   QIOclose(qp);

HISTORY
       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Updated by
       Russ Allbery <eagle@eyrie.org>.

       $Id: qio.pod 9767 2014-12-07 21:13:43Z iulius $

INN 2.6.3			  2015-09-12				qio(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | HISTORY

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

home | help