stream.h File Reference

Functions for working with stream targets (that is, FILE pointers). More...

Go to the source code of this file.

Functions
STUMPLESS_PUBLIC_FUNCTION void	stumpless_close_stream_target (const struct stumpless_target *target)
	Closes a stream target.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_target *	stumpless_open_stderr_target (const char *name)
	Opens a stream target for the stderr stream.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_target *	stumpless_open_stdout_target (const char *name)
	Opens a stream target for the stdout stream.
STUMPLESS_PUBLIC_FUNCTION struct stumpless_target *	stumpless_open_stream_target (const char *name, FILE *stream)
	Opens a stream target for the given stream.

Detailed Description

Functions for working with stream targets (that is, FILE pointers).

Thread Safety: MT-Safe Logging to stream targets is thread safe. A mutex is used to coordinate writes to the stream.

Async Signal Safety: AS-Unsafe lock Logging to stream targets is not signal safe, as a non-reentrant lock is used to coordinate writes to the stream.

Async Cancel Safety: AC-Unsafe lock Logging to stream targets is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed.

Function Documentation

stumpless_close_stream_target()

STUMPLESS_PUBLIC_FUNCTION void stumpless_close_stream_target

(

const struct stumpless_target *

target

)

Closes a stream target.

This function does NOT close the stream associated with the target. It does destroy all memory allocated for the target, including the target struct itself.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads would use if they tried to reference this target.

Async Signal Safety: AS-Unsafe lock heap This function is not safe to call from signal handlers due to the destruction of a lock that may be in use as well as the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe lock heap This function is not safe to call from threads that may be asynchronously cancelled, as the cleanup of the lock may not be completed, and the memory deallocation function may not be AC-Safe itself.

Parameters

target

The stream target to close.

Examples

filter_example.c, and stream_example.c.

stumpless_open_stderr_target()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_target * stumpless_open_stderr_target

(

const char *

name

)

Opens a stream target for the stderr stream.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not modified by any other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory allocation functions.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, as the memory allocation function may not be AC-Safe itself.

Parameters

name	The name of the target to open. This is only used for identification of the target.

Returns

The opened target if no error is encountered. In the event of an error, NULL is returned and an error code is set appropriately.

Examples

chain_example.c.

stumpless_open_stdout_target()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_target * stumpless_open_stdout_target

(

const char *

name

)

Opens a stream target for the stdout stream.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not modified by any other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory allocation functions.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, as the memory allocation function may not be AC-Safe itself.

Parameters

name	The name of the target to open. This is only used for identification of the target.

Returns

The opened target if no error is encountered. In the event of an error, NULL is returned and an error code is set appropriately.

Examples

chain_example.c, entry_example.c, filter_example.c, and severity_level_example.c.

stumpless_open_stream_target()

STUMPLESS_PUBLIC_FUNCTION struct stumpless_target * stumpless_open_stream_target	(	const char *	name,
		FILE *	stream )

Opens a stream target for the given stream.

Events logged to this target will be separated by a newline, just as with a file target. In fact, a stream target is equivalent to a file target with the difference being that the file must be opened and closed by the caller.

A stream target can also be useful for logging to other streams, such as stdout and stderr, which is not possible with a file target.

Thread Safety: MT-Safe race:name This function is thread safe, of course assuming that name is not modified by any other threads during execution.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of memory allocation functions.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, as the memory allocation function may not be AC-Safe itself.

Parameters

name	The name of the target to open. This is only used for identification of the target.
stream	The stream to log events to.

Returns

The opened target if no error is encountered. In the event of an error, NULL is returned and an error code is set appropriately.

Examples

stream_example.c.