File Logging

Data Structures
struct	LogFileConfig

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

Enumerations
enum	LOG_DATE_FORMATS {   LOG_DateISO , LOG_DateISOCompact , LOG_DateNCSA , LOG_DateSyslog ,   LOG_DateISOCompactMsec }
	Timestamp format options for log file output. More...
enum	LOG_FLAGS {   LOG_LocalTime = 0x0001 , LOG_OmitLevel = 0x0002 , LOG_ShortLevel = 0x0004 , LOG_BracketLevel = 0x0008 ,   LOG_JustifyLevel = 0x0010 , LOG_IncludeCategory = 0x0020 , LOG_BracketCategory = 0x0040 , LOG_AddColon = 0x0080 ,   LOG_CategoryFirst = 0x0100 }
	Formatting flags for log file output. More...
enum	LOG_ROTATE_MODE { LOG_RotateSize = 1 , LOG_RotateTime }
	Log rotation mode. More...

Functions
LogFileData *	logfileCreate (VFS *vfs, strref filename, LogFileConfig *config)
LogDest *	logfileRegister (int maxlevel, LogCategory *catfilter, LogFileData *logfile)
LogDest *	logfileRegisterWithDefer (int maxlevel, LogCategory *catfilter, LogFileData *logfile, LogDest *deferdest)
void	logfileMsgFunc (int level, LogCategory *cat, int64 timestamp, strref msg, uint32 batchid, 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.

Basic Usage:

LogFileConfig cfg = {
    .dateFormat = LOG_DateISO,
    .rotateMode = LOG_RotateSize,
    .rotateSize = 10 * 1024 * 1024,  // 10MB
    .rotateKeepFiles = 5,
    .spacing = 2,
    .flags = LOG_IncludeCategory
};
 
LogFileData *lfd = logfileCreate(vfs, _S"app.log", &cfg);
LogDest *dest = logfileRegister(LOG_Info, NULL, lfd);
 
// Later, unregister to close
logUnregisterDest(dest);

Typedef Documentation

LogFileConfig

typedef struct LogFileConfig LogFileConfig

Configuration for file-based logging

Controls output formatting, rotation behavior, and retention policies.

Enumeration Type Documentation

LOG_DATE_FORMATS

enum LOG_DATE_FORMATS

Timestamp format options for log file output.

Enumerator
LOG_DateISO	ISO 8601 format: "2026-01-02 15:04:05".
LOG_DateISOCompact	Compact ISO: "20260102 150405".
LOG_DateNCSA	NCSA Common Log format: "02/Jan/2026:15:04:05 +0000".
LOG_DateSyslog	Syslog format: "Jan 2 15:04:05".
LOG_DateISOCompactMsec	Compact ISO with milliseconds: "20260102 150405.123".

Definition at line 35 of file logfile.h.

LOG_FLAGS

enum LOG_FLAGS

Formatting flags for log file output.

Enumerator
LOG_LocalTime	Use local time instead of UTC.
LOG_OmitLevel	Do not include severity level.
LOG_ShortLevel	Use single-character level abbreviations.
LOG_BracketLevel	Enclose log level in brackets [INFO].
LOG_JustifyLevel	Make level a fixed-width column.
LOG_IncludeCategory	Include category name in output.
LOG_BracketCategory	Enclose category in brackets [Network].
LOG_AddColon	Add colon after the prefix.
LOG_CategoryFirst	Category between date and level instead of at end.

Definition at line 44 of file logfile.h.

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 57 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,
		LogFileConfig *	config
	)

Create a file logging destination

Initializes a file-based log destination with the specified configuration. 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	Logging configuration (copied, caller retains ownership)

Returns

File logging handle, or NULL on failure

LogFileConfig cfg = {
    .dateFormat = LOG_DateISO,
    .rotateMode = LOG_RotateSize,
    .rotateSize = 10 * 1024 * 1024,
    .spacing = 2,
    .flags = LOG_IncludeCategory | LOG_BracketLevel
};
LogFileData *lfd = logfileCreate(vfs, _S"server.log", &cfg);

logfileMsgFunc()

void logfileMsgFunc	(	int	level,
		LogCategory *	cat,
		int64	timestamp,
		strref	msg,
		uint32	batchid,
		void *	userdata
	)

Log message callback for file destinations

Formats and writes a log message to the file. Checks for rotation after each write.

Parameters

level	Log severity level
cat	Category, or NULL for default
timestamp	Wall clock timestamp
msg	Log message text
batchid	Batch identifier for grouping
userdata	LogFileData pointer from logfileCreate()

logfileRegister()

LogDest * logfileRegister	(	int	maxlevel,
		LogCategory *	catfilter,
		LogFileData *	logfile
	)

Register a file destination with the logging system

Registers the file as a log destination. Messages will be formatted according to the configuration and written to the file. The file destination will be automatically cleaned up when unregistered.

Parameters

maxlevel	Maximum log level to write to file
catfilter	Category filter, or NULL for all non-private categories
logfile	File logging handle from logfileCreate()

Returns

Destination handle for later unregistration, or NULL on failure

logfileRegisterWithDefer()

LogDest * logfileRegisterWithDefer	(	int	maxlevel,
		LogCategory *	catfilter,
		LogFileData *	logfile,
		LogDest *	deferdest
	)

Register a file destination and flush deferred logs

Atomically registers a file destination while flushing previously deferred logs to it. This ensures all logs from application startup are captured even if the log file couldn't be opened immediately.

Parameters

maxlevel	Maximum log level to write to file
catfilter	Category filter, or NULL for all non-private categories
logfile	File logging handle from logfileCreate()
deferdest	Deferred destination to flush (destroyed during this call)

Returns

Destination handle for later unregistration, or NULL on failure

// Early in startup - buffer logs temporarily
LogDeferData *deferdata = logDeferCreate();
LogDest *deferdest = logDeferRegister(LOG_Info, NULL, deferdata);
 
// Later - open file and transfer buffered logs
LogFileData *lfd = logfileCreate(vfs, _S"app.log", &cfg);
LogDest *dest = logfileRegisterWithDefer(LOG_Info, NULL, lfd, deferdest);