Taking a run's number in a folder of the card, and which open file keeps a listed name out of reach. More...

#include <stdbool.h>
#include <stddef.h>
#include "card_tree.h"
#include "log_name.h"

Data Structures
struct	log_take_io_t
	The card. `dir` is a path from the root, CARD_ROOT the root itself. More...
struct	log_series_t
	One folder's numbering. More...
struct	log_series_set_t
	Numbering of the folders a run can be written to. More...
struct	log_marks_t
	The files the logger has open, each with the folder it is in: the automatic log's run in `run_dir`, and a test's CSV and report in `test_dir`. More...

Macros
#define	LOG_TAKE_TRIES 3u
	How many free numbers a failing create is given before the folder is called full.
#define	LOG_SERIES_SLOTS 2
	The folders a run can be written to: the auto logs' and the user's.

Typedefs
typedef void(*)	log_take_visit_fn(const char name, void visit_ctx)
	Receives one directory entry's name; it does not outlive the call.

Enumerations
enum	log_take_t { LOG_TAKE_OK = 0 , LOG_TAKE_ARG , LOG_TAKE_NO_CARD , LOG_TAKE_NO_FOLDER , LOG_TAKE_UNREADABLE , LOG_TAKE_FULL }
	What a take came to. More...

Functions
void	log_series_init (log_series_set_t *set)
	Every folder's numbering forgotten: the next take walks its folder.
void	log_series_forget_all (void)
	Every set forgets every folder's numbering before its next take: the card's files were changed by another hand than the logger's (FILES' copy, move, rename, new entry or delete), so a folder may hold a higher number than a set handed out last.
log_series_t *	log_series_of (log_series_set_t set, const char dir)
	The numbering of folder `dir`, case folded: its slot, or a free one, or the slot `set` gives up next, cleared.
bool	log_series_follow (log_series_set_t set, char took, const char *want)
	One kind of file follows its folder setting: `want` is the folder of its next take, and `took` (CARD_DIR_MAX bytes) the folder of the last one.
log_take_t	log_take (log_series_set_t set, const log_take_io_t io, const char dir, log_prefix_t prefix, bool report, int number)
	Make folder `dir`, take the next free number of its series and create the run's file under `prefix:` the CSV, or with `report` the TXT. `number` takes the number on LOG_TAKE_OK and -1 otherwise.
bool	log_marks_busy (const log_marks_t marks, const char dir, const char *name)
	Whether `name` in folder `dir` is a file the logger is still writing, or one whose deletion would remove such a file (log_name_busy()), by the marks of that folder alone: an open USER/LOGS/ATEST005.CSV does not hold back BENCH/LOGS/SERVO005.CSV.

Detailed Description

Taking a run's number in a folder of the card, and which open file keeps a listed name out of reach.

The logger writes each run under a number from its folder's series (log_name.h): one above the highest number the folder holds, under any prefix, read by one directory walk the first time the folder is written and remembered after that. Before a number is taken its 10 names (LOG_NAME_FORMS) are probed, so a file written since the walk is stepped over and not overwritten.

The folder is made on the way, one level at a time: "BENCH", then "BENCH/LOGS". A level that is there already is not an error; a level whose name a file holds is, and so is a card that takes no new folder.

A failed take forgets the folder's number, so the next take walks the folder again: the operator's answer to a full folder is to delete a file, and that deletion counts from the next run on.

The card is reached through log_take_io_t, functions the caller supplies, so the rules run on a host without a card. Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ LOG_TAKE_TRIES

#define LOG_TAKE_TRIES 3u

How many free numbers a failing create is given before the folder is called full.

The walk has put the number above every one the folder holds, so a refused create is the volume answering and not a name.

Enumeration Type Documentation

◆ log_take_t

enum log_take_t

What a take came to.

Enumerator
LOG_TAKE_ARG	a NULL, a prefix not written, a long dir
LOG_TAKE_NO_CARD	no card is mounted
LOG_TAKE_NO_FOLDER	a level of the folder cannot be made
LOG_TAKE_UNREADABLE	the folder does not read to its end
LOG_TAKE_FULL	no free number, or LOG_TAKE_TRIES creates refused

Function Documentation

◆ log_marks_busy()

bool log_marks_busy	(	const log_marks_t *	marks,
		const char *	dir,
		const char *	name )

Whether name in folder dir is a file the logger is still writing, or one whose deletion would remove such a file (log_name_busy()), by the marks of that folder alone: an open USER/LOGS/ATEST005.CSV does not hold back BENCH/LOGS/SERVO005.CSV.

Folders compare with case folded. With both kinds in one folder, both kinds' marks apply.

Parameters

marks	The open files.
dir	The folder of the file.
name	The file name.

Returns: true when the file is busy.

◆ log_series_follow()

bool log_series_follow	(	log_series_set_t *	set,
		char *	took,
		const char *	want )

One kind of file follows its folder setting: want is the folder of its next take, and took (CARD_DIR_MAX bytes) the folder of the last one.

A folder other than took, case folded, is copied into it and forgets every folder's numbering in set, so the next take of each kind walks its folder and numbers from what that folder holds. A file already open stays in the folder it was opened in. True when the folder changed; false for the same folder, a NULL or a want that does not fit.

Parameters

set	The numbering set.
took	The folder of the last take, CARD_DIR_MAX bytes.
want	The folder of the next take.

Returns: true when the folder changed.

◆ log_series_forget_all()

void log_series_forget_all ( void )

Every set forgets every folder's numbering before its next take: the card's files were changed by another hand than the logger's (FILES' copy, move, rename, new entry or delete), so a folder may hold a higher number than a set handed out last.

A count, safe to call from any task: log_take() compares it with the set's own and walks the folder when it moved.

◆ log_series_init()

void log_series_init ( log_series_set_t * set )

Every folder's numbering forgotten: the next take walks its folder.

Parameters

set	The numbering set.

◆ log_series_of()

log_series_t * log_series_of	(	log_series_set_t *	set,
		const char *	dir )

The numbering of folder dir, case folded: its slot, or a free one, or the slot set gives up next, cleared.

Two kinds of run in one folder share one series. NULL for a NULL argument or a dir that does not fit CARD_DIR_MAX.

Parameters

set	The numbering set.
dir	The folder path.

Returns: The slot of the folder, or NULL.

◆ log_take()

log_take_t log_take	(	log_series_set_t *	set,
		const log_take_io_t *	io,
		const char *	dir,
		log_prefix_t	prefix,
		bool	report,
		int *	number )

Make folder dir, take the next free number of its series and create the run's file under prefix: the CSV, or with report the TXT. number takes the number on LOG_TAKE_OK and -1 otherwise.

prefix is one this firmware writes (below LOG_PREFIX_WRITTEN).

Parameters

set	The numbering set.
io	The card functions.
dir	The folder, from the root.
prefix	The file prefix.
report	true for the TXT report, false for the CSV.
number	Receives the run number on LOG_TAKE_OK, else -1.

Returns: LOG_TAKE_OK, or the reason no number was taken.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LOG_TAKE_TRIES

Enumeration Type Documentation

◆ log_take_t

Function Documentation

◆ log_marks_busy()

◆ log_series_follow()

◆ log_series_forget_all()

◆ log_series_init()

◆ log_series_of()

◆ log_take()