fesText.h File Reference

Definitions for the text file routines. More...

Functions

int fesTextClose (void *hndl)

Close a text file.

int fesTextDisp (const char *name, int first, int nLine, int pSize)

Display the contents of a text file.

int fesTextFlush (void *hndl)

Flush data to a text file.

int fesTextOpenR (void **hndl, const char *name)

Open a text file for reading.

int fesTextOpenW (void **hndl, const char *name)

Open a text file for writing.

int fesTextPosition (void *hndl, long long rqst, long long *posn)

Position a text file by byte.

int fesTextRead (void *hndl, char *data, int dLeng, int *rLeng)

Read a line from a text file.

int fesTextSeek (void *hndl, int whence, int nLine)

Position a text file by line.

int fesTextSize (void *hndl, long long *size)

Get the size of a text file.

int fesTextWrite (void *hndl, const char *data, int dLeng)

Write to a text file.

Detailed Description

Definitions for the text file routines.

Author:: Owen H Saxton

$Id: fesText.h,v 1.2 2010/07/26 19:08:54 saxton Exp $

Function Documentation

int fesTextClose ( void * hndl )

Close a text file.

This routine closes a text file.

Parameters:

hndl

The handle of the file, returned when the file was opened.

Return values:

	FES_SUCCESS	The file was successfully closed.
	FES_INVHNDL	Invalid text file handle.

References fesFileClose().

Referenced by fesTextDisp().

int fesTextDisp	(	const char *	name,
		int	first,
		int	nLine,
		int	pSize
	)

Display the contents of a text file.

This routine reads a text file and displays its contents, starting from a specified line.

Parameters:

	name	The name of the text file to be displayed.
	first	The first line to display, numbering from 0. If negative, counts backwards from the end of the file.
	nLine	The number of lines to display. If not positive, all lines up to the end of the file are displayed.
	pSize	The page size to use. This is the number of lines to display at a time before pausing to prompt for the next page. If zero, the default value of 24 is used. If negative, the output is not paused.

Returns:: Always 0.

References fesTextClose(), fesTextOpenR(), fesTextRead(), fesTextSeek(), FFS_END, and FFS_START.

Referenced by fesXctlLogDisp().

int fesTextFlush ( void * hndl )

Flush data to a text file.

This routine flushes all buffered data to a text file.

Parameters:

hndl

The handle of the file, returned when the file was opened.

Return values:

	FES_SUCCESS	The file was successfully flushed.
	FES_INVHNDL	Invalid text file handle.

References fesFileFlush().

int fesTextOpenR	(	void **	hndl,
		const char *	name
	)

Open a text file for reading.

This routine opens the specified text file for reading.

Parameters:

	hndl	The address of a pointer to receive the handle of the open file.
	name	The address of the name of the file to be opened. This may start with a node name separated from the rest of the name by a colon. In this case, the file is opened on the remote node.

Return values:

FES_SUCCESS

The file was successfully opened.

References fesFileClose(), fesFileOpen(), and FFO_RDONLY.

Referenced by fesTextDisp().

int fesTextOpenW	(	void **	hndl,
		const char *	name
	)

Open a text file for writing.

This routine opens the specified text file for writing, creating it if necessary, and positioning at the end of the file.

Parameters:

	hndl	The address of a pointer to receive the handle of the open file.
	name	The address of the name of the file to be opened. This may start with a node name separated from the rest of the name by a colon. In this case, the file is opened on the remote node.

Return values:

FES_SUCCESS

The file was successfully opened.

References fesFileOpen(), FFO_APPEND, FFO_CREAT, and FFO_WRONLY.

int fesTextPosition	(	void *	hndl,
		long long	rqst,
		long long *	posn
	)

Position a text file by byte.

This routine seeks to a new absolute byte position in a text file. If the new position lies beyond the file, the file is positioned at the end. If the new position is not at the beginning of a line, it is moved to the beginning of the current line.

Parameters:

	hndl	The handle of the file, returned when the file was opened.
	rqst	The requested new position. If negative, the position is not changed.
	posn	The address of a 64-bit integer to receive the actual byte position in the file, which is not necessarily the same as the requested position. If NULL, the new position is not returned.

Return values:

	FES_SUCCESS	The positioning was successful.
	FES_INVHNDL	Invalid text file handle.
	FES_FILWRONL	The file is open for writing.
	FES_xxx	An error occurred.

int fesTextRead	(	void *	hndl,
		char *	data,
		int	dLeng,
		int *	rLeng
	)

Read a line from a text file.

This routine reads data from a text file, up through the first newline encountered, or until the specified length has been read, or the end of file reached.

Parameters:

	hndl	The handle of the file, returned when the file was opened.
	data	The address where the read data is to be stored.
	dLeng	The maximum number of bytes to read.
	rLeng	The address of an integer to receive the number of bytes read.

Return values:

	FES_SUCCESS	The read was successful.
	FES_INVHNDL	Invalid text file handle.
	FES_EOFREAD	End of file was reached.
	FES_FILWRONL	Attempt to read from file opened for writing.
	FES_RECTRUNC	Data area too small to hold complete record.
	FES_UNEXPEOF	Last record not terminated with a newline.

Referenced by fesTextDisp().

int fesTextSeek	(	void *	hndl,
		int	whence,
		int	nLine
	)

Position a text file by line.

This routine seeks to a new line position in a text file. If the new position lies outside the file, the file is positioned at the nearest file extremity, and error status returned.

Parameters:

	hndl	The handle of the file, returned when the file was opened.
	whence	The base for the new offset (FFS_START, FFS_CURR, or FFS_END).
	nLine	The new line offset in the file.

Return values:

	FES_SUCCESS	The positioning was successful.
	FES_INVHNDL	Invalid text file handle.
	FES_FILWRONL	The file is open for writing.
	FES_INVLSEEK	The seek goes outside the file.

References FFS_END, and FFS_START.

Referenced by fesTextDisp().

int fesTextSize	(	void *	hndl,
		long long *	size
	)

Get the size of a text file.

This routine returns the size of a text file.

Parameters:

	hndl	The handle of the file, returned when the file was opened.
	size	The address of a 64-bit integer to receive the size of the file.

Return values:

	FES_SUCCESS	The write was successful.
	FES_INVHNDL	Invalid text file handle.
	FES_FILWRONL	The file is open only for writing.

int fesTextWrite	(	void *	hndl,
		const char *	data,
		int	dLeng
	)

Write to a text file.

This routine writes data to a text file and follows it with a newline.

Parameters:

	hndl	The handle of the file, returned when the file was opened.
	data	The address of the data to be written.
	dLeng	The number of bytes to write.

Return values:

	FES_SUCCESS	The write was successful.
	FES_INVHNDL	Invalid text file handle.
	FES_FILRDONL	The file is open only for reading.

References fesFileWrite().


Functions
int	fesTextClose (void *hndl)
	Close a text file.
int	fesTextDisp (const char *name, int first, int nLine, int pSize)
	Display the contents of a text file.
int	fesTextFlush (void *hndl)
	Flush data to a text file.
int	fesTextOpenR (void *hndl, const char name)
	Open a text file for reading.
int	fesTextOpenW (void *hndl, const char name)
	Open a text file for writing.
int	fesTextPosition (void hndl, long long rqst, long long posn)
	Position a text file by byte.
int	fesTextRead (void hndl, char data, int dLeng, int *rLeng)
	Read a line from a text file.
int	fesTextSeek (void *hndl, int whence, int nLine)
	Position a text file by line.
int	fesTextSize (void hndl, long long size)
	Get the size of a text file.
int	fesTextWrite (void hndl, const char data, int dLeng)
	Write to a text file.