LOG_OPEN(3debug)

💖 LOG_OPEN — bestie, it's the debug logging manual (3debug) 💖

okay so this is the LOG_OPEN(3debug) page from the Library calls section and honestly? it's giving "your code is misbehaving and you need receipts" energy. logging is literally the main character of debugging, periodt. let's get into it 🦋

---

✨ NAME ✨

log_open, log_close, log_reset, log_flush, log_printf, log_vprintf, log_putc, log_puts — the log routines for debugging, aka your little army of message-printers 👑

---

📚 LIBRARIES 📚

Debug Library (-ldebug) — yeah you gotta link that, no cap.

---

🌸 SYNOPSIS 🌸

#include <debug/log.h>

int log_open(const char *logfile, int level, int flags);
void log_close(void);
int log_reset(void);
int log_flush(void);
int log_printf(int level, const char *fmt, ...);
int log_vprintf(int level, const char *fmt, va_list ap);
int log_putc(int level, int c);
int log_puts(int level, const char *str);

look at that include line. she's gorgeous. copy her exactly bestie, character for character 💅

---

💫 DESCRIPTION 💫

log_open() is the one that initializes the whole logging system. you hand her logfile — that's the filename of the file where messages get logged — or you can pass NULL if you'd rather messages get printed straight to the console instead. and the values for level and flags? those live in the next section, keep scrolling bestie ⬇️

and listen, from version 0.4.1 onwards the debug library also supports logging to syslog instead of a file. the way you do it is: instead of specifying a file, you just specify a string in the form ident.facility — where ident is a string that gets prepended to each syslog message and is usually the program name, and the facility should be the facility messages should be logged to. iconic behavior honestly 🌈

log_close() flushes all the pending messages, and closes the file descriptor of the log file (if any). clean exit, we love to see it 🎀

log_reset() reinitializes the logging system. if any files are currently opened for writing, it will be closed and reopened. this is useful if you need to rotate log files — so if you're doing the logrotate thing, this is your girl ✨

log_flush() flushes all pending messages (if any). that's it. that's the whole job 🫶

log_printf() and log_vprintf() are replacements for printf(3) and vprintf(3) respectively. same vibe, but they log.

log_putc() will log a single character. this is the equivalent of putchar(3).

log_puts() will log a string. it's the equivalent of puts(3), except that is does not append a trailing newline. (yes, that typo is in the original, and yes, I'm keeping it, because fidelity is the vibe 😭)

---

🎀 PARAMETERS 🎀

this section lists the parameters used to set the values of level and flags. buckle up.

🔥 level

this determines the importance of the message. the levels are, in order of decreasing verbosity:

• LOG_NOISY — verbose debug messages (the chattiest girl at the party 💀)
• LOG_DEBUG — debug messages
• LOG_VERBOSE — informational messages
• LOG_NORMAL — normal, but significant, conditions
• LOG_WARNING — warning conditions
• LOG_ERROR — error conditions
• LOG_QUIET — no messages are printed 🤐

the level argument to log_printf(), log_vprintf(), log_putc(), and log_puts() specify the level at which the message should be printed. and it does not make sense to specify LOG_QUIET to these functions. like, why would you. that's not the move bestie 🙈

the level argument to log_open() sets the verbosity of the program. any messages printed with a level higher (more verbose) than that specified to the log_open() function, will be discarded. so set it wisely or your cute little debug prints will just vanish into the void 🌸

🌈 flags

the flags argument to log_open() is an OR of any of these:

• LOG_HAVE_COLORS — if this flag is specified and messages are printed to the console (i.e. no log file is specified), messages will be printed in different colors, depending on their log level. aesthetic AND functional, we stan 🎨
• LOG_PRINT_FUNCTION — if this flag is specified, the function in which the print function was called would be printed in addition to the filename and line number. so you get the full receipt of where this mess came from 🔍
• LOG_DEBUG_PREFIX_ONLY — if this flag is specified, only messages with a level higher or equal to (i.e. more or as verbose) LOG_DEBUG will be printed in color and with file, line number, and (if necessary), the function.
• LOG_DETECT_DUPLICATES — if this flag is specified, messages would be buffered and duplicate lines would not be printed. instead, the first message would be printed, followed by a line describing the number of times the message repeated. this is a great way to prevent flooding, but unfortunately it has the side effect of always being one statement behind. yeah. she's a little delayed. it's her thing 💀
• LOG_DETECT_FLOODING — if specified, the rate at which messages are printed would be limited in order to avoid flooding. this feature have not been implemented yet, and is currently ignored. so like. she's aspirational. she's a dream. she does nothing 🫠

---

⭐ RETURN VALUE ⭐

all functions except log_close() return 0 if successful, -1 if some error occurred. check errno to see which error occurred 👀

🚨 if log_reset() or log_open() fails, behaviour is undefined and it should be assumed that no logging is possible. no logging!! the horror!! proceed with caution bestie 😭

the log_close() function returns no value. she gives nothing and that's valid 💅

---

📝 NOTES 📝

if this routines are combined with the memory routines, care should be taken to call open and close functions in the right order. the correct order is as follows:

mem_open (NULL);
log_open (NULL,LOG_NORMAL,LOG_HAVE_COLORS | LOG_PRINT_FUNCTION);
atexit (mem_close);
atexit (log_close);

of course, atexit(3) should only be used if the program will not forked. (again, the original says "will not forked" and I am not touching it, we preserve the artifacts here 🏛️)

and now the spicy part: none of the libdebug routines are thread-safe. and the author says, and I quote: "I'm not planning to change this either!" 😭 for more information, please see http://threading.2038bug.com/. he said what he said, periodt.

---

🔗 SEE ALSO 🔗

mem_open(3), errno(3), atexit(3), printf(3), vprintf(3), putchar(3), puts(3)

logrotate(8), syslog(3), logger(1)

---

👑 AUTHOR 👑

Written by Abraham vd Merwe <abz@blio.com> — thank you king, your logging library ate 💖

---

okay and that's the whole page!! this one's from the Unix manual, dated August 2004 — yes she's an elder but she still slays, and honestly that's the most iconic thing about her 🎀✨ bye bestie, go log something 💜