File Logging

Data Structures
struct	LogFileConfig

Typedefs
typedef struct LogFileConfig	LogFileConfig
typedef struct LogFileData	LogFileData
	Opaque handle for file logging state.

Enumerations
enum	LOG_ROTATE_MODE { LOG_RotateSize = 1 , LOG_RotateTime }
	Log rotation mode. More...

Functions
LogDest *	logfileRegister (int maxlevel, strref chanfilter, VFS *vfs, strref filename, const LogFileConfig *config, LogSerializer *ser)
LogFileData *	logfileCreate (VFS *vfs, strref filename, const LogFileConfig *config, LogSerializer *ser)
void	logfileMsgFunc (const LogRecord *rec, void *userdata)
void	logfileBatchFunc (uint32 batchid, void *userdata)
void	logfileCloseFunc (void *userdata)

Detailed Description

File-based logging destination with support for automatic log rotation, flexible formatting, and customizable output options. Files can be rotated based on size or time, with configurable retention policies.

The file is a transport: it owns opening, rotation and retention, and takes a serializer that decides what a record looks like on the way in (see Log Serializers). The same rotating file therefore holds text or NDJSON depending only on what it was given.

Basic Usage:

LogFileConfig cfg = {
    .rotateMode = LOG_RotateSize,
    .rotateSize = 10 * 1024 * 1024,  // 10MB
    .rotateKeepFiles = 5,
};
LogTextConfig tcfg = { .dateFormat = LOG_DateISO, .flags = LOG_IncludeChannel };
 
LogDest *dest = logfileRegister(LOG_Info, NULL, vfs, _SL("app.log"), &cfg,
                                logTextSerializer(&tcfg));
 
// ...or the same rotation policy, written as NDJSON
LogDest *jdest = logfileRegister(LOG_Info, NULL, vfs, _SL("app.ndjson"), &cfg,
                                 logNdjsonSerializer(NULL));
 
// Later, unregister to close
logUnregisterDest(dest);

Typedef Documentation

LogFileConfig

typedef struct LogFileConfig LogFileConfig

Configuration for file-based logging

Controls rotation behavior and retention policies. Output formatting belongs to the serializer the file is created with, not here.

Enumeration Type Documentation

LOG_ROTATE_MODE

enum LOG_ROTATE_MODE

Log rotation mode.

Enumerator
LOG_RotateSize	Rotate when file exceeds rotateSize bytes.
LOG_RotateTime	Rotate at specified time of day.

Definition at line 44 of file logfile.h.

Function Documentation

logfileBatchFunc()

void logfileBatchFunc	(	uint32	batchid,
		void *	userdata
	)

Batch completion callback for file destinations

Flushes the file buffer to ensure batch messages are written together.

Parameters

batchid	Completed batch identifier
userdata	LogFileData pointer from logfileCreate()

logfileCloseFunc()

void logfileCloseFunc

(

void *

userdata

)

Cleanup callback for file destinations

Closes the log file and releases resources.

Parameters

userdata

LogFileData pointer from logfileCreate()

logfileCreate()

LogFileData * logfileCreate	(	VFS *	vfs,
		strref	filename,
		const LogFileConfig *	config,
		LogSerializer *	ser
	)

Create a file logging destination

Only needed to register the file by hand with logRegisterDest() – logfileRegister() does this and the registration together. The returned handle belongs to exactly one destination: it is closed and freed by logfileCloseFunc() and cannot be registered twice.

The file is opened immediately and created if it doesn't exist. If rotation is enabled, existing rotated log files are scanned to enforce retention policies.

Parameters

vfs	Virtual filesystem to use for file operations
filename	Path to the log file
config	Rotation configuration (copied, caller retains ownership)
ser	Serializer to render records with; ownership transfers, including if this call fails. NULL gets a default text serializer.

Returns

File logging handle, or NULL on failure

LogFileConfig cfg = { .rotateMode = LOG_RotateSize, .rotateSize = 10 * 1024 * 1024 };
LogFileData *lfd = logfileCreate(vfs, _SL("server.log"), &cfg, NULL);
LogDest *dest = logRegisterDest(LOG_Info, NULL, logfileMsgFunc, logfileBatchFunc,
                                logfileCloseFunc, lfd);

logfileMsgFunc()

void logfileMsgFunc	(	const LogRecord *	rec,
		void *	userdata
	)

Log message callback for file destinations

Renders and writes a log record to the file. Checks for rotation after each write.

Parameters

rec	Log record to write
userdata	LogFileData pointer from logfileCreate()

logfileRegister()

LogDest * logfileRegister	(	int	maxlevel,
		strref	chanfilter,
		VFS *	vfs,
		strref	filename,
		const LogFileConfig *	config,
		LogSerializer *	ser
	)

Register a file logging destination

Opens the log file and registers it with the logging system in one step. The file is created if it doesn't exist, and if rotation is enabled, existing rotated log files are scanned to enforce retention policies. Records are serialized and written to the file; it is closed when logUnregisterDest() retires the returned handle.

Parameters

maxlevel	Maximum log level to write to the file
chanfilter	Channel path pattern, or NULL for every unrestricted channel
vfs	Virtual filesystem to use for file operations
filename	Path to the log file
config	Rotation configuration (copied, caller retains ownership)
ser	Serializer to render records with; ownership transfers, including if this call fails. NULL gets a default text serializer.

Returns

Destination handle for later unregistration, or NULL if the file could not be opened or the destination could not be registered

LogFileConfig cfg = {
    .rotateMode = LOG_RotateSize,
    .rotateSize = 10 * 1024 * 1024,
};
LogTextConfig tcfg = { .flags = LOG_IncludeChannel | LOG_BracketLevel };
LogDest *dest = logfileRegister(LOG_Info, NULL, vfs, _SL("server.log"), &cfg,
                                logTextSerializer(&tcfg));