Pantheios file Stock Back-end
[Pantheios Stock Back-ends]

---

Detailed Description

Back-end library that outputs to a file.

Modules
	Pantheios file Stock Back-end Flags
	Flags for the Pantheios file Stock Back-end.
Classes
struct	pan_be_file_init_t
	Structure used for specifying initialisation information to the be.file library. More...
Functions
void	pantheios_be_file_getAppInit (int backEndId, pan_be_file_init_t *init)
	Callback function defined by the application, invoked when the API is initialised with a NULL init parameter.
int	pantheios_be_file_init (PAN_CHAR_T const *processIdentity, int id, pan_be_file_init_t const *init, void *reserved, void **ptoken)
	Implements the functionality for pantheios_be_init() over the file API.
void	pantheios_be_file_uninit (void *token)
	Implements the functionality for pantheios_be_uninit() over the file API.
int	pantheios_be_file_logEntry (void *feToken, void *beToken, int severity, PAN_CHAR_T const *entry, size_t cchEntry)
	Implements the functionality for pantheios_be_logEntry() over the file API.
int	pantheios_be_file_flush (int backEndId)
	Flushes one/all back-ends.
int	pantheios_be_file_setFilePath (PAN_CHAR_T const *fileName, pan_be_file_init_t::pan_uint32_t fileMask, pan_be_file_init_t::pan_uint32_t fileFlags, int backEndId)
	Sets/changes the log file name for a single back-end.
int	pantheios_be_file_setFilePath (PAN_CHAR_T const *fileName)
	Sets/changes the log file name for all back-ends.
int	pantheios_be_file_setFilePath (PAN_CHAR_T const *fileName, int backEndId)
	Sets/changes the log file name for all back-ends.

---

Function Documentation

int pantheios_be_file_flush

(

int

backEndId

)

Flushes one/all back-ends.

Parameters:

backEndId

The back-end identifier. If this is PANTHEIOS_BEID_ALL, then all back-ends will be flushed.

void pantheios_be_file_getAppInit	(	int	backEndId,
		pan_be_file_init_t *	init
	)

Callback function defined by the application, invoked when the API is initialised with a NULL init parameter.

Parameters:

	backEndId	The back-end identifier passed to the back-end during its initialisation.
	init	A pointer to an already-initialised instance of pan_be_file_init_t.

If any application-specific changes are required they can be made to the structure to which init points, which will already have been initialised. These changes will then be incorporated into the back-end state, and reflected in its behaviour.

If no changes are required, then the function can be a simple stub, containing no instructions.

Note:

This function is only required when the callback version of the library is used.

Exceptions:

throw()

This function must not throw any exceptions!

Warning:

This function will be called during the initialisation of Pantheios, and so must not make any calls into Pantheios, either directly or indirectly!

Examples:

cpp/backends/example.cpp.backends.file.callback/example.cpp.backends.file.callback.cpp.

int pantheios_be_file_init	(	PAN_CHAR_T const *	processIdentity,
		int	id,
		pan_be_file_init_t const *	init,
		void *	reserved,
		void **	ptoken
	)

Implements the functionality for pantheios_be_init() over the file API.

int pantheios_be_file_logEntry	(	void *	feToken,
		void *	beToken,
		int	severity,
		PAN_CHAR_T const *	entry,
		size_t	cchEntry
	)

Implements the functionality for pantheios_be_logEntry() over the file API.

int pantheios_be_file_setFilePath	(	PAN_CHAR_T const *	fileName,
		int	backEndId
	)			[inline]

Sets/changes the log file name for all back-ends.

Parameters:

	fileName	The (absolute or relative) name of the log file to be used with the given back-end.
	backEndId	The back-end identifier. If this is PANTHEIOS_BEID_ALL, then all back-ends will be initialised with the file-name.

int pantheios_be_file_setFilePath

(

PAN_CHAR_T const *

fileName

)

[inline]

Sets/changes the log file name for all back-ends.

Parameters:

fileName

The (absolute or relative) name of the log file to be used with the given back-end.

pantheios_be_file_setFilePath	(	PAN_CHAR_T const *	fileName,
		pan_be_file_init_t::pan_uint32_t	fileMask,
		pan_be_file_init_t::pan_uint32_t	fileFlags,
		int	backEndId
	)

Sets/changes the log file name for a single back-end.

Parameters:

	fileName	The (absolute or relative) name of the log file to be used with the given back-end.
	fileMask	A bitmask that controls which values of the flags are to be interpreted in the fileFlags parameter.
	fileFlags	The flags that control the file creation - only PANTHEIOS_BE_FILE_F_TRUNCATE is recognised by this function.
	backEndId	The back-end identifier. If this is PANTHEIOS_BEID_ALL, then all back-ends will be initialised with the file-name.

Note:

In the case where you are using be.file for both local and remote back-ends, specifying PANTHEIOS_BEID_ALL will, on most platforms, result in the remote back-end failing to write output, because the local back-end will hold an exclusive lock on the file.

Examples:

c/example.c.N/example.c.N.c, cpp/backends/example.cpp.backends.file.lrsplit/example.cpp.backends.file.lrsplit.cpp, and cpp/backends/example.cpp.backends.file/example.cpp.backends.file.cpp.

void pantheios_be_file_uninit

(

void *

token

)

Implements the functionality for pantheios_be_uninit() over the file API.

pantheios Library documentation © Matthew Wilson & Synesis Software, 2006-2011