Data Structures
struct	_PERCI_RECORD
struct	_PERCI_WRITER
struct	_PERCI_READER
Defines
#define	PERCI_MAX_RECORDS 256
#define	PERCI_RECSIZE 256
#define	PERCI_DATASIZE (PERCI_RECSIZE - sizeof(perci_reclen_t))
Typedefs
typedef uint8_t	perci_recnum_t
typedef uint_fast8_t	perci_fast_recnum_t
typedef uint8_t	perci_reclen_t
typedef uint_fast8_t	perci_fast_reclen_t
typedef struct _PERCI_RECORD	PERCI_RECORD
typedef struct _PERCI_WRITER	PERCI_WRITER
typedef struct _PERCI_READER	PERCI_READER
Functions
int	PerCiInit (char *path, int recs)
	Initialize a ring buffer file.
PERCI_WRITER *	PerCiOpen (char *path)
	Open a ring buffer file.
void	PerCiClose (PERCI_WRITER *writer)
	Close a ring buffer file.
void	PerCiFlush (PERCI_WRITER *writer)
	Flush the current write buffer.
int	PerCiWrite (PERCI_WRITER writer, const char data, int len)
	Write to a ring buffer file.
int	PerCiWriteFormat (PERCI_WRITER writer, const char fmt,...)
	Write formatted line to a ring buffer file.
int	PerCiWriteVarList (PERCI_WRITER writer, const char fmt, va_list ap)
	Write formatted line to a ring buffer file.
PERCI_READER *	PerCiAttachReader (PERCI_WRITER *writer)
	Start reading from a ring buffer file.
void	PerCiDetachReader (PERCI_READER *reader)
	Stop reading from a ring buffer file.
int	PerCiRead (PERCI_READER reader, char data, int len)
	Read data from a ring buffer file.
int	PerCiReadLine (PERCI_READER reader, char line, int len)
	Read a text line from a ring buffer file.
void	PerCiDump (FILE stream, char path)
	Dump ring buffer file to given stream.
Variables
perci_reclen_t	_PERCI_RECORD::pcd_len
uint8_t	_PERCI_RECORD::pcd_data [PERCI_RECSIZE]
int	_PERCI_WRITER::pcw_fd
long	_PERCI_WRITER::pcw_size
HANDLE	_PERCI_WRITER::pcw_mutex
perci_fast_recnum_t	_PERCI_WRITER::pcw_recnum
PERCI_RECORD	_PERCI_WRITER::pcw_rec
PERCI_WRITER *	_PERCI_READER::pcr_cil
perci_fast_recnum_t	_PERCI_READER::pcr_recnum
perci_fast_reclen_t	_PERCI_READER::pcr_reclen
perci_fast_reclen_t	_PERCI_READER::pcr_recpos

Define Documentation

#define PERCI_MAX_RECORDS 256

Referenced by PerCiOpen().

#define PERCI_RECSIZE 256

Referenced by PerCiFlush(), PerCiInit(), PerCiOpen(), and PerCiWrite().

#define PERCI_DATASIZE (PERCI_RECSIZE - sizeof(perci_reclen_t))

Referenced by PerCiDump(), PerCiOpen(), PerCiWrite(), and PerCiWriteVarList().

Typedef Documentation

typedef uint8_t perci_recnum_t

typedef uint_fast8_t perci_fast_recnum_t

typedef uint8_t perci_reclen_t

typedef uint_fast8_t perci_fast_reclen_t

typedef struct _PERCI_RECORD PERCI_RECORD

typedef struct _PERCI_WRITER PERCI_WRITER

typedef struct _PERCI_READER PERCI_READER

Function Documentation

int PerCiInit	(	char *	path,
		int	recs
	)

Initialize a ring buffer file.

If the file doesn't exist, a new file will be created. If the file exists, any buffered data will be erased.

The total size of the file is

 recs * PERCI_RECSIZE + sizeof(perci_reclen_t)

bytes.

The available data space is

 recs * PERCI_DATASIZE

bytes.

Parameters:

path	Path name of the file.
recs	Number of buffer records, at least 2.

Returns:: 0 on success and -1 on failure.

References _close(), _O_BINARY, _O_CREAT, _O_RDWR, _O_TRUNC, _open(), _write(), calloc, free(), NULL, NUTASSERT, and PERCI_RECSIZE.

Here is the call graph for this function:

PERCI_WRITER * PerCiOpen ( char * path )

Open a ring buffer file.

The file must have been created by a previous call to PerCiInit().

The function failes, if the file doesn't exist or if it is corrupted. Applications may use the following sequence to open a circular buffer.

 PERCI_WRITER *perci;
 char *path = "UFLASH0:data.log";

 while ((perci = PerCiOpen(path)) == NULL) {
     if (PerCiInit(path, 128)) {
         printf("Error %d creating %s\n", errno, path);
         break;
     }
 }

Parameters:

path	Path name of the file.

Returns:: A pointer to a PERCI_WRITER structure on success. The return of a NULL pointer indicates a failure.

References _close(), _filelength(), _O_BINARY, _O_RDWR, _open(), _read(), _seek(), calloc, free(), NULL, NUTASSERT, NutEventPost(), _PERCI_RECORD::pcd_data, _PERCI_RECORD::pcd_len, _PERCI_WRITER::pcw_fd, _PERCI_WRITER::pcw_mutex, _PERCI_WRITER::pcw_rec, _PERCI_WRITER::pcw_recnum, _PERCI_WRITER::pcw_size, PERCI_DATASIZE, PERCI_MAX_RECORDS, PERCI_RECSIZE, SEEK_CUR, and SEEK_SET.

Here is the call graph for this function:

void PerCiClose ( PERCI_WRITER * writer )

Close a ring buffer file.

Parameters:

writer Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().

References _close(), free(), NULL, NUTASSERT, _PERCI_RECORD::pcd_len, _PERCI_WRITER::pcw_fd, _PERCI_WRITER::pcw_rec, and PerCiFlush().

Here is the call graph for this function:

void PerCiFlush ( PERCI_WRITER * writer )

Flush the current write buffer.

Parameters:

writer Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().

References _seek(), _write(), NULL, NUTASSERT, _PERCI_RECORD::pcd_len, _PERCI_WRITER::pcw_fd, _PERCI_WRITER::pcw_rec, _PERCI_WRITER::pcw_recnum, PERCI_RECSIZE, and SEEK_SET.

Referenced by PerCiClose().

Here is the call graph for this function:

int PerCiWrite	(	PERCI_WRITER *	writer,
		const char *	data,
		int	len
	)

Write to a ring buffer file.

Parameters:

writer Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().

Returns:: The number of bytes successfully written or -1 on failure.

References _seek(), _write(), memcpy(), NULL, NUT_WAIT_INFINITE, NUTASSERT, NutEventPost(), NutEventWait(), _PERCI_RECORD::pcd_data, _PERCI_RECORD::pcd_len, _PERCI_WRITER::pcw_fd, _PERCI_WRITER::pcw_mutex, _PERCI_WRITER::pcw_rec, _PERCI_WRITER::pcw_recnum, _PERCI_WRITER::pcw_size, PERCI_DATASIZE, PERCI_RECSIZE, and SEEK_SET.

Referenced by PerCiWriteVarList().

Here is the call graph for this function:

int PerCiWriteFormat	(	PERCI_WRITER *	writer,
		const char *	fmt,
			...
	)

Write formatted line to a ring buffer file.

Parameters:

writer	Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().
fmt	Format string containing conversion specifications like printf.

Returns:: The number of bytes successfully written or -1 on failure.

References NULL, NUTASSERT, PerCiWriteVarList(), and rc.

Here is the call graph for this function:

int PerCiWriteVarList	(	PERCI_WRITER *	writer,
		const char *	fmt,
		va_list	ap
	)

Write formatted line to a ring buffer file.

Alternate form of PerCiWriteFormat(), in which the arguments have already been captured using the variable-length argument facilities.

Parameters:

writer	Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().
fmt	Format string containing conversion specifications like printf.
ap	Pointer to the list of arguments.

Returns:: The number of bytes successfully written or -1 on failure.

References free(), malloc(), NULL, NUTASSERT, PERCI_DATASIZE, PerCiWrite(), strlen(), and vsprintf().

Referenced by PerCiWriteFormat().

Here is the call graph for this function:

PERCI_READER * PerCiAttachReader ( PERCI_WRITER * writer )

Start reading from a ring buffer file.

It is assumed, that the ring buffer is kept open while the application is running. From time to time the buffered data will be retrieved. Therefore, a reader is attached to a previously open file and reading starts at the oldest record.

When all data has been read, the application must call PerCiDetachReader() to relase all allocated resources for reading.

Multiple readers may be concurrently attached to the same file.

Parameters:

writer Pointer to a PERCI_WRITER structure obtained by a previous call to PerCiOpen().

Returns:: A pointer to a PERCI_READER structure on success. The return of a NULL pointer indicates a failure.

References malloc(), NULL, NUTASSERT, _PERCI_READER::pcr_cil, _PERCI_READER::pcr_reclen, _PERCI_READER::pcr_recnum, _PERCI_READER::pcr_recpos, and _PERCI_WRITER::pcw_recnum.

Here is the call graph for this function:

void PerCiDetachReader ( PERCI_READER * reader )

Stop reading from a ring buffer file.

Parameters:

reader Pointer to a PERCI_READER structure obtained by a previous call to PerCiAttachReader().

References free(), NULL, and NUTASSERT.

Here is the call graph for this function:

int PerCiRead	(	PERCI_READER *	reader,
		char *	data,
		int	len
	)

Read data from a ring buffer file.

Parameters:

reader	Pointer to a PERCI_READER structure obtained by a previous call to PerCiAttachReader().
data	Pointer to the buffer that receives the data.
len	Number of bytes to read.

Returns:: The number of bytes read. If this is lower than the requested length, then we reached the end.

References _read(), memcpy(), NULL, NUTASSERT, _PERCI_RECORD::pcd_data, _PERCI_READER::pcr_cil, _PERCI_READER::pcr_reclen, _PERCI_READER::pcr_recnum, _PERCI_READER::pcr_recpos, _PERCI_WRITER::pcw_fd, _PERCI_WRITER::pcw_rec, and _PERCI_WRITER::pcw_recnum.

Referenced by PerCiReadLine().

Here is the call graph for this function:

int PerCiReadLine	(	PERCI_READER *	reader,
		char *	line,
		int	len
	)

Read a text line from a ring buffer file.

Parameters:

reader	Pointer to a PERCI_READER structure obtained by a previous call to PerCiAttachReader().
data	Pointer to the buffer that receives the data.
len	Number of bytes to read.