mtree parsing and manipulation library

• Student: Michal Ratajsky (michal@FreeBSD.org)
• Mentor: Brooks Davis (brooks@FreeBSD.org)

FreeBSD currently includes several tools that work with file system hierarchy descriptions and each contains its own routines to parse and/or manipulate these descriptions.

This project attempts to improve this by designing a library to include all the common code, removing duplications from application code and allowing simple future extensions.

The library will provide an API for specfile-related operations that are currently present in the mtree tool and other tools as well as additional manipulations (filter, merge, update and possibly others) that could be useful to applications in the future or allow expansion of the mtree tool.

The API will be designed to be intuitive, well documented and easily useable by applications.

Some code will be reused from existing applications, mainly from the mtree tool. All reused code will be verified and eventually adapted or rewritten to fit the required abstraction.

The library will include complete API documentation and unit tests.

Applications and libraries that contain mtree code will be modified to use libmtree instead:

• mtree
• libarchive
• makefs
• xinstall

The mtree tool itself will be distributed in the same source tree as libmtree. Both libmtree and mtree will be implemented portably.

• May 25: Start of coding
• June 26: Fully functional libmtree and mtree with support for reading, writing, comparison of spec files
• June 26-July 3: Mid-term Evaluations
• July 5: Fully functional mtree with support for all current features and command-line options
• July 26: All applications and libraries ported to libmtree
• August 9: Complete and fully documented libmtree and mtree
• August 17: FreeBSD source tree updated to include libmtree and the new mtree implementation
• August 17: End of coding (soft)
• August 21 19:00 UTC: End of coding (hard)

• https://github.com/mratajsky/libmtree

/*
 * Initialize/free/reset mtree_spec
 */
mtree_spec *mtree_spec_init();
void        mtree_spec_free(mtree_spec *spec);
void        mtree_spec_reset(mtree_spec *spec);
 
/*
 * Spec reader
 */
 
/* Read from a specfile */
int         mtree_spec_read_specfile(mtree_spec *spec, const char *path);
 
/* Read from data */
int         mtree_spec_read_data(mtree_spec *spec, const char *data, int len);
 
/* Finish reading from data
 * This is needed to parse remaining data in the buffer and reset internal state
 * to allow another read from somewhere else */
int         mtree_spec_read_data_end(mtree_spec *spec);
 
/* Read from a directory structure */
int         mtree_spec_read_dir(mtree_spec *spec, const char *path);
 
/*
 * NOTES:
 * The reader's functions may be called multiple times, following a single write
 * call to create a merged spec.
 */
 
/*
 * Spec writer
 */
 
/* Write the mtree_spec to a specfile */
int         mtree_spec_write_specfile(mtree_spec *spec, const char *path);
 
/* Send each spec line to a user-defined function
 * XXX this is probably not a great name, see how other bsd libs call this
 * if there are any */
int         mtree_spec_write_user(mtree_spec *spec, mtree_spec_write_func func);
 
/*
 * Spec comparator
 */
 
/* Compare against another spec
 * XXX this needs a way to notify the application about each difference, probably
 * it should call a user-defined function for each difference, but it should also
 * allow not calling anything and just return a result */
int         mtree_spec_compare_spec(mtree_spec *spec, mtree_spec *other);
 
/* Compare against directory structure
 * It would be also possible to use mtree_spec_read_dir to create another mtree_spec
 * from dir structure and use mtree_spec_compare, but this function should exist to
 * do this more efficiently by comparing while walking the dir tree */
int         mtree_spec_compare_dir(mtree_spec *spec, const char *path);
 
/*
 * Get the top entry from a spec
 */
mtree_entry *mtree_spec_get_entry(mtree_spec *spec);
 
/*
 * Other spec functions, TBD later...
 */
 
/* Call user-defined function on each mtree_entry of the spec */
void        mtree_spec_foreach_entry(mtree_spec *spec, mtree_spec_foreach_func func);
 
/* Call user-defined function on each mtree_entry of the spec
 * If the function returns 0, remove the entry from the spec */
void        mtree_spec_foreach_entry_filter(mtree_spec *spec, mtree_spec_filter_func func);
 
/*
 * mtree entry functions - probably a linked list
 */
 
mtree_entry *mtree_entry_init();
void         mtree_entry_free();
 
mtree_entry *mtree_entry_next(mtree_entry *entry);
 
/*
 * XXX these are not good the way they are, rethink it, maybe they shouldn't even
 * be there
 */
 
/* Add a new entry after the current one */
mtree_entry *mtree_entry_add(mtree_entry *entry, mtree_entry *new_entry);
 
/* Remove the current entry */
mtree_entry *mtree_entry_remove(mtree_entry *entry);
 
/*
 * XXX mtree_entry_as_string() comes to mind, but it wouldn't be possible to use
 * /set and stuff, all the info would have to be included in a single line,
 * see if there is any potential user of this
 */

• mtree specification
• GSoC Project Idea