The file manager's jobs, one step at a time (fm_ops.h). More...

#include "fm_ops.h"
#include <string.h>
#include "log_name.h"

Enumerations
enum	{ STEP_CHECK = 0 , STEP_DATA , STEP_SYNC , STEP_UNLINK , STEP_RENAME }
	The steps of a job, in the order they run. A job without data does all of its work in STEP_CHECK. More...

Functions
static fm_err_t	refuse (fm_job_t *job, fm_err_t err)
	Hold a refusal in the job, so fm_job_state() says it too.
static void	begin (fm_job_t *job, fm_job_kind_t kind, unsigned mount)
	Clear `job` and name what it does.
static fm_err_t	run (fm_job_t *job)
	Let a checked job run.
static fm_err_t	join (char out, const char dir, const char *name, bool is_dir)
	The path of `name` in folder `dir` (fm_path_join()).
static fm_err_t	tmp_path (char out, const char dir, const char *name)
	Write the path of `name's` ".NEW" in `dir` into `out`.
fm_err_t	fm_job_copy (fm_job_t job, const fm_bench_t bench, unsigned mount, const char src_dir, const char name, const char *dst_dir)
	Copy file `name` of folder `src_dir` into folder `dst_dir` under the same name.
static fm_err_t	target_path (fm_job_t job, const fm_bench_t bench, const char dir, const char name, bool is_dir)
	The checks MOVE and RENAME share on the target: not a LOCKED or FAULT name, and a path that fits.
fm_err_t	fm_job_move (fm_job_t job, const fm_bench_t bench, unsigned mount, const char src_dir, const char name, bool is_dir, const char *dst_dir)
	Move file or empty folder `name` of `src_dir` into `dst_dir`.
fm_err_t	fm_job_rename (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name, bool is_dir, const char *new_name)
	Give entry `name` of folder `dir` the name `new_name`.
fm_err_t	fm_job_delete (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name, bool is_dir)
	Delete file or empty folder `name` of folder `dir`.
static fm_err_t	start_new (fm_job_t job, const fm_bench_t bench, const char dir, const char name)
	The checks NEW's two jobs share.
fm_err_t	fm_job_mkdir (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name)
	Make folder `name` in folder `dir`.
fm_err_t	fm_job_create (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name)
	Make the empty file `name` in folder `dir`.
fm_err_t	fm_job_save (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name, uint64_t len, fm_fill_fn fill, void *fill_ctx)
	Write `len` bytes from `fill` as file `name` of folder `dir`, through "<name>.NEW" (the file's comment).
fm_err_t	fm_job_load (fm_job_t job, const fm_bench_t bench, unsigned mount, const char dir, const char name, uint8_t *buf, size_t cap)
	Read file `name` of folder `dir` into `buf`. A read: the gate does not stop it.
static fm_job_state_t	finish (fm_job_t job, const fm_io_t io, fm_job_state_t state, fm_err_t err, bool drop)
	End the job: close what is open and, when `drop`, remove the ".NEW" it wrote.
static fm_err_t	free_name (const fm_io_t io, const char path)
	Whether `path` is free for a new entry.
static fm_err_t	there (const fm_io_t io, const char path, bool is_dir, fm_stat_t *st)
	Whether `path` is there as the kind the job expects.
static void	count_entry (const fm_dirent_t e, void vctx)
	Count one entry of a folder that has to be empty.
static fm_err_t	empty_dir (const fm_io_t io, const char path)
	Whether folder `path` holds nothing, those names included that the walk cannot list.
static fm_err_t	single (fm_job_t job, const fm_io_t io)
	The single calls of MOVE, RENAME, DELETE, MKDIR and CREATE, with their checks.
static fm_err_t	open_files (fm_job_t job, const fm_io_t io)
	The first step of a job with data: the names checked and the files opened.
static fm_err_t	one_chunk (fm_job_t job, const fm_io_t io, uint8_t *chunk, size_t size)
	One chunk of a copy, a save or a load.
static fm_op_t	op_of (fm_job_kind_t kind)
	The operation the rules are asked about for a job's kind.
static fm_err_t	still_allowed (const fm_job_t job, const fm_bench_t bench)
	Whether the rules let the job go on as the bench stands now: fm_allowed() of the source of a copy, a load, a move, a rename or a delete, of the file a save writes, or of the folder NEW makes something in.
static fm_job_state_t	data_step (fm_job_t job, const fm_io_t io, const fm_bench_t bench, uint8_t chunk, size_t size)
	One step of a copy, a save or a load.
fm_job_state_t	fm_job_step (fm_job_t job, const fm_io_t io, const fm_bench_t bench, uint8_t chunk, size_t size)
	Run the job's next step.
void	fm_job_cancel (fm_job_t *job)
	Ask the job to stop at its next chunk. A single call that has started finishes.
fm_job_state_t	fm_job_state (const fm_job_t job, uint64_t done, uint64_t *total)
	Where the job stands.

Detailed Description

The file manager's jobs, one step at a time (fm_ops.h).

SPDX-License-Identifier: MIT

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

The steps of a job, in the order they run. A job without data does all of its work in STEP_CHECK.

Enumerator
STEP_CHECK	the card's answers on the names; the opens
STEP_DATA	one chunk
STEP_SYNC	the ".NEW" on the card, and closed
STEP_UNLINK	a save's old file deleted
STEP_RENAME	the ".NEW" given its name

Function Documentation

◆ begin()

void begin	(	fm_job_t *	job,
		fm_job_kind_t	kind,
		unsigned	mount )

static

Clear job and name what it does.

Parameters

job	the job
kind	what it does
mount	the mount its names are from

◆ count_entry()

void count_entry	(	const fm_dirent_t *	e,
		void *	vctx )

static

Count one entry of a folder that has to be empty.

Parameters

e	the entry
vctx	an unsigned count

◆ data_step()

fm_job_state_t data_step	(	fm_job_t *	job,
		const fm_io_t *	io,
		const fm_bench_t *	bench,
		uint8_t *	chunk,
		size_t	size )

static

One step of a copy, a save or a load.

Parameters

job	the job
io	the card, held
bench	the gate as it stands now
chunk	the chunk's room
size	its bytes

Returns: the job's state after the step

◆ empty_dir()

fm_err_t empty_dir	(	const fm_io_t *	io,
		const char *	path )

static

Whether folder path holds nothing, those names included that the walk cannot list.

Parameters

io	the card, held
path	the folder

Returns: FM_OK; FM_ERR_NOT_EMPTY; the card's failure

◆ finish()

fm_job_state_t finish	(	fm_job_t *	job,
		const fm_io_t *	io,
		fm_job_state_t	state,
		fm_err_t	err,
		bool	drop )

static

End the job: close what is open and, when drop, remove the ".NEW" it wrote.

Parameters

job	the job
io	the card, held
state	FM_JOB_DONE, FM_JOB_STOPPED or FM_JOB_FAILED
err	why, FM_OK for DONE
drop	remove job->tmp

Returns: state

◆ fm_job_cancel()

void fm_job_cancel ( fm_job_t * job )

Ask the job to stop at its next chunk. A single call that has started finishes.

Parameters

job the job

◆ fm_job_copy()

fm_err_t fm_job_copy	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	src_dir,
		const char *	name,
		const char *	dst_dir )

Copy file name of folder src_dir into folder dst_dir under the same name.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the names were listed from
src_dir	the source's folder
name	the file's name
dst_dir	the target folder

Returns: FM_OK when the job runs; else the refusal, which the job holds as FM_JOB_FAILED: FM_ERR_ARG, FM_ERR_ARMED, FM_ERR_LOGGING, FM_ERR_BUSY, FM_ERR_LOCKED, FM_ERR_FIXED, FM_ERR_SAME for one folder, FM_ERR_NAME

◆ fm_job_create()

fm_err_t fm_job_create	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name )

Make the empty file name in folder dir.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the folder was listed from
dir	the folder to make it in
name	the new file's name

Returns: FM_OK, or the refusal

◆ fm_job_delete()

fm_err_t fm_job_delete	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name,
		bool	is_dir )

Delete file or empty folder name of folder dir.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the names were listed from
dir	the folder
name	the entry's name
is_dir	the entry is a folder

Returns: FM_OK, or the refusal

◆ fm_job_load()

fm_err_t fm_job_load	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name,
		uint8_t *	buf,
		size_t	cap )

Read file name of folder dir into buf. A read: the gate does not stop it.

Parameters

job	the job
bench	the rules; may be NULL
mount	the mount the file was listed from
dir	the file's folder
name	the file's name
buf	takes the bytes
cap	room in `buf`; a larger file is FM_ERR_TOO_BIG

Returns: FM_OK, or the refusal

◆ fm_job_mkdir()

fm_err_t fm_job_mkdir	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name )

Make folder name in folder dir.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the folder was listed from
dir	the folder to make it in
name	the new folder's name

Returns: FM_OK, or the refusal

◆ fm_job_move()

fm_err_t fm_job_move	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	src_dir,
		const char *	name,
		bool	is_dir,
		const char *	dst_dir )

Move file or empty folder name of src_dir into dst_dir.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the names were listed from
src_dir	the source's folder
name	the entry's name
is_dir	the entry is a folder
dst_dir	the target folder

Returns: FM_OK, or the refusal as fm_job_copy(); FM_ERR_SAME also for a folder moved into itself

◆ fm_job_rename()

fm_err_t fm_job_rename	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name,
		bool	is_dir,
		const char *	new_name )

Give entry name of folder dir the name new_name.

A change of case alone is a rename of one entry, not an overwrite.

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the names were listed from
dir	the folder
name	the entry's name now
is_dir	the entry is a folder
new_name	its new name

Returns: FM_OK, or the refusal; FM_ERR_ARG for the same name

◆ fm_job_save()

fm_err_t fm_job_save	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		unsigned	mount,
		const char *	dir,
		const char *	name,
		uint64_t	len,
		fm_fill_fn	fill,
		void *	fill_ctx )

Write len bytes from fill as file name of folder dir, through "<name>.NEW" (the file's comment).

Parameters

job	the job
bench	the gate and the rules; may be NULL
mount	the mount the file was read from
dir	the file's folder
name	the file's name; it need not be there yet
len	the text's bytes
fill	hands over the bytes
fill_ctx	passed to `fill`

Returns: FM_OK, or the refusal

◆ fm_job_state()

fm_job_state_t fm_job_state	(	const fm_job_t *	job,
		uint64_t *	done,
		uint64_t *	total )

Where the job stands.

Parameters

job	the job; NULL is FM_JOB_IDLE
done	takes the bytes done; may be NULL
total	takes the bytes to do; may be NULL

Returns: its state

◆ fm_job_step()

fm_job_state_t fm_job_step	(	fm_job_t *	job,
		const fm_io_t *	io,
		const fm_bench_t *	bench,
		uint8_t *	chunk,
		size_t	size )

Run the job's next step.

Parameters

job	the job
io	the card
bench	the gate as it stands now; may be NULL
chunk	room for one chunk of a copy, a save or a load
size	bytes `chunk` takes; FM_CHUNK on the panel

Returns: the job's state after the step

◆ free_name()

fm_err_t free_name	(	const fm_io_t *	io,
		const char *	path )

static

Whether path is free for a new entry.

Parameters

io	the card, held
path	the path

Returns: FM_OK for no such name; FM_ERR_EXISTS; or the card's failure

◆ join()

fm_err_t join	(	char *	out,
		const char *	dir,
		const char *	name,
		bool	is_dir )

static

The path of name in folder dir (fm_path_join()).

Parameters

out	room for FM_PATH_SIZE bytes
dir	the folder
name	the entry's name
is_dir	the entry is a folder: it counts in the depth

Returns: FM_OK, or FM_ERR_NAME for a path too long or too deep

◆ one_chunk()

fm_err_t one_chunk	(	fm_job_t *	job,
		const fm_io_t *	io,
		uint8_t *	chunk,
		size_t	size )

static

One chunk of a copy, a save or a load.

Parameters

job	the job
io	the card, held
chunk	the chunk's room
size	its bytes

Returns: FM_OK, with job->step moved on at the data's end; or why not

◆ op_of()

fm_op_t op_of ( fm_job_kind_t kind )

static

The operation the rules are asked about for a job's kind.

Parameters

kind	the job's kind

Returns: its fm_op_t

◆ open_files()

fm_err_t open_files	(	fm_job_t *	job,
		const fm_io_t *	io )

static

The first step of a job with data: the names checked and the files opened.

Parameters

job	the job
io	the card, held

Returns: FM_OK or why not

◆ refuse()

fm_err_t refuse	(	fm_job_t *	job,
		fm_err_t	err )

static

Hold a refusal in the job, so fm_job_state() says it too.

Parameters

job	the job
err	the refusal

Returns: err

◆ run()

fm_err_t run ( fm_job_t * job )

static

Let a checked job run.

Parameters

job the job

Returns: FM_OK

◆ single()

fm_err_t single	(	fm_job_t *	job,
		const fm_io_t *	io )

static

The single calls of MOVE, RENAME, DELETE, MKDIR and CREATE, with their checks.

Parameters

job	the job
io	the card, held

Returns: FM_OK or why not

◆ start_new()

fm_err_t start_new	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		const char *	dir,
		const char *	name )

static

The checks NEW's two jobs share.

Parameters

job	the job, which takes the new path
bench	the gate and the rules; may be NULL
dir	the folder to make it in
name	the new name

Returns: FM_OK or the refusal, which the job holds

◆ still_allowed()

fm_err_t still_allowed	(	const fm_job_t *	job,
		const fm_bench_t *	bench )

static

Whether the rules let the job go on as the bench stands now: fm_allowed() of the source of a copy, a load, a move, a rename or a delete, of the file a save writes, or of the folder NEW makes something in.

Parameters

job	the job
bench	the bench now

Returns: FM_OK or the refusal

◆ target_path()

fm_err_t target_path	(	fm_job_t *	job,
		const fm_bench_t *	bench,
		const char *	dir,
		const char *	name,
		bool	is_dir )

static

The checks MOVE and RENAME share on the target: not a LOCKED or FAULT name, and a path that fits.

Parameters

job	the job, which takes the target's path
bench	the rules; may be NULL
dir	the target folder
name	the target name
is_dir	the entry is a folder

Returns: FM_OK or the refusal

◆ there()

fm_err_t there	(	const fm_io_t *	io,
		const char *	path,
		bool	is_dir,
		fm_stat_t *	st )

static

Whether path is there as the kind the job expects.

Parameters

io	the card, held
path	the path
is_dir	a folder is expected
st	takes the answer

Returns: FM_OK; FM_ERR_ARG for the other kind; the card's answer

◆ tmp_path()

fm_err_t tmp_path	(	char *	out,
		const char *	dir,
		const char *	name )

static

Write the path of name's ".NEW" in dir into out.

Parameters

out	room for FM_PATH_SIZE bytes
dir	the folder
name	the file's name

Returns: FM_OK, or FM_ERR_NAME when it does not fit

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ begin()

◆ count_entry()

◆ data_step()

◆ empty_dir()

◆ finish()

◆ fm_job_cancel()

◆ fm_job_copy()

◆ fm_job_create()

◆ fm_job_delete()

◆ fm_job_load()

◆ fm_job_mkdir()

◆ fm_job_move()

◆ fm_job_rename()

◆ fm_job_save()

◆ fm_job_state()

◆ fm_job_step()

◆ free_name()

◆ join()

◆ one_chunk()

◆ op_of()

◆ open_files()

◆ refuse()

◆ run()

◆ single()

◆ start_new()

◆ still_allowed()

◆ target_path()

◆ there()

◆ tmp_path()