API_HighLvl::lib::core

Collaboration diagram for API_HighLvl::lib::core:

Data Structures
struct	SprOptDesc

Namespaces
	xref_spr_dt_examples
	Working with SprDT data types, some examples
	xref_spr_file_hdr
	File formats and headers
	xref_spr_sig_handling
	Handling asynchronous events (signals) in SPRAAK
	xref_spr_class
	Working with SPRAAK classes and objects
	xref_spr_class_example1
	"Example using C++ style multiple inheritance"
	xref_spr_class_example2
	"Example using single inheritance and Java/objective-C style interfaces"
	xref_spr_stream_principles
	Data IO in SPRAAK

Functions
int	spraak_ini_prog (void *restrict dst, const SprOptDesc *restrict od, const char *const *argv, SprMsgId *restrict prog)
void	spraak_fini_prog (void *restrict dst, const SprOptDesc *restrict od, SprMsgId *restrict prog)
int	spraak_ini (void)
void	spraak_fini (void)
SprStream *	spr_stream_close (SprStream *restrict fd)
	Close a stream. More...
SprStream *	spr_stream_open (const char *restrict fname, unsigned int flags, SprKeySet *restrict keys)

Detailed Description

Function Documentation

int spraak_ini_prog	(	void *restrict	dst,
		const SprOptDesc *restrict	od,
		const char *const *	argv,
		SprMsgId *restrict	prog
	)

Parse the program arguments argv using the option description od. The converted arguments are converted according to the type of the matching option, and the result is written back in dst (the matching option points to the approriate field).

Returns

0 on success and -1 on failure (initalization of the SPRAAK environment failed, or one or more required arguments is/are not specified or an illegal option is specified).

Parameters

dst	Structure to store the decoded arguments.
od	Option description array.
argv	Argument values.
prog	Identify the calling program.

void spraak_fini_prog	(	void *restrict	dst,
		const SprOptDesc *restrict	od,
		SprMsgId *restrict	prog
	)

Free all program arguments, finalize (close) the SPRAAK environment and close stdin, stdout and stderr.

Parameters

dst	Structure that stores the decoded arguments.
od	Option description array.
prog	Identify the calling program.

int spraak_ini

(

void

)

Initialize (open) the SPRAAK environment.

Note

Multiple calls to spraak_ini() are allowed. The SPRAAK environment will be initialized only once.

spraak_fini() must be called exactely as many times as spraak_ini() was called.

Returns

(-1) on failure and 0 on success

void spraak_fini

(

void

)

Finalize (close) the SPRAAK environment.

Note

Multiple calls to spraak_fini() are allowed. The SPRAAK environment will be closed on the Nth call, N being the number of times spraak_ini() was called.

spraak_fini() must be called exactely as many times as spraak_ini() was called.

Returns

(-1) on failure and 0 on success

SprStream* spr_stream_close

(

SprStream *restrict

fd

)

Close a stream.

Close a stream descriptor, so that it no longer refers to any file, pipe, device, ... and release all associated resources. Since nothing can be done about a failing close() operation, no error value is returned. However, as is the case with any error, an error message will be written to the message system to indicate the problem.

Returns

The NULL pointer.

Parameters

fd	Stream object.

SprStream* spr_stream_open	(	const char *restrict	fname,
		unsigned int	flags,
		SprKeySet *restrict	keys
	)

Open the stream (file) the (rich) file name fname refers to. The flags argument can be a combination of the following flags:

SPR_STREAM_CREATE

Create the file if it does not exist.

SPR_STREAM_TRUNC

When opening a file for writing, truncate the file to length 0.

SPR_STREAM_APPEND

Open the file and position the write pointer to the end of the file.

SPR_STREAM_READ

Open the file for reading (the default).

SPR_STREAM_WRITE

Open the file for writing.

SPR_STREAM_RW

Open the file for reading and writing. The stream will be put in WRITE mode initialy if the CREATE, TRUNC or APPEND flag is set as well, otherwise the initial mode for the stream will be the READ mode.

SPR_STREAM_LINEBUF

Buffer the IO operations on a line by line base instead of the normal 4K blocks.

SPR_STREAM_UNBUF

Do minimal (i.e. almost no) buffering on the IO operations.

SPR_STREAM_SILENT

Do not report read/write/close errors on this stream via the message system.

SPR_STREAM_SILENTEOF

Do not report EOF errors on this stream via the message system.

SPR_STREAM_NONBLOCK

Open the file in a non-blocking mode, i.e. reads will return the available amount of data only, writes may not write all requested data, so retries may be needed.

SPR_STREAM_KEEPKSET

Do not free the keyset given as argument to the spr_stream_open() routine when opening the stream fails.

SPR_STREAM_NOHDR

Open the file without writing/reading a header.

SPR_STREAM_SEEK

Make sure random seeks on the file are possible.

SPR_STREAM_REWIND

Make sure a rewind (full restart) on the file is possible.

SPR_STREAM_AUTOCLOSE

Automatically close the file when the program terminates.

SPR_STREAM_AUTORM

Automatically close and remove the file when the program terminates.

SPR_STREAM_ASCII

Force the stream in ASCII mode after opening it.

When opening a file for writing, the keys argument is the set of keys that will make up the file header (keys may equal NULL when opening a header-less file for writing).
When opening a file for reading, the keys argument may either be NULL or may point to a existing set of keys. In the latter case, the keys found in the file will be added to keys, overwriting existing keys with the same name. In other words, when opening for reading, the keys argument can be used to provide default values of certain keys.
If a non NULL keys argument is given, the ownership of keys will be transfered to the freshly opened stream (the return value). keys will be freed if the stream fails to open (a NULL return value), except when the SPR_STREAM_KEEPKSET flag is set.

Returns

A valid stream handler or NULL on error.