`libmagic` API coverage

[robo9k]

Tracking issue to document what parts of the libmagic API are (not) covered by the magic / magic-sys crate (yet)
Can eventually be used as a roadmap for magic@1 release / feature completion

https://github.com/file/file/blob/master/src/magic.h.in (at the time of writing libmagic v5.47)

magic.h C header	magic-sys crate	magic crate
MAGIC_NONE	MAGIC_NONE	cookie::Flags::default()
MAGIC_DEBUG	MAGIC_DEBUG	cookie::Flags::DEBUG
MAGIC_SYMLINK	MAGIC_SYMLINK	cookie::Flags::SYMLINK
MAGIC_COMPRESS	MAGIC_COMPRESS	cookie::Flags::COMPRESS
MAGIC_DEVICES	MAGIC_DEVICES	cookie::Flags::DEVICES
MAGIC_MIME_TYPE	MAGIC_MIME_TYPE	cookie::Flags::MIME_TYPE
MAGIC_CONTINUE	MAGIC_CONTINUE	cookie::Flags::CONTINUE
MAGIC_CHECK	MAGIC_CHECK	cookie::Flags::CHECK
MAGIC_PRESERVE_ATIME	MAGIC_PRESERVE_ATIME	cookie::Flags::PRESERVE_ATIME
MAGIC_PRESERVE_ATIME	MAGIC_PRESERVE_ATIME	cookie::Flags::PRESERVE_ATIME
MAGIC_RAW	MAGIC_RAW	cookie::Flags::RAW
MAGIC_ERROR	MAGIC_ERROR	cookie::Flags::ERROR
MAGIC_MIME_ENCODING	MAGIC_MIME_ENCODING	cookie::Flags::MIME_ENCODING
MAGIC_MIME	MAGIC_MIME	cookie::Flags::MIME
MAGIC_APPLE	MAGIC_APPLE	cookie::Flags::APPLE
MAGIC_EXTENSION	MAGIC_EXTENSION	cookie::Flags::EXTENSION
MAGIC_COMPRESS_TRANSP	MAGIC_COMPRESS_TRANSP	cookie::Flags::COMPRESS_TRANSP
MAGIC_NO_COMPRESS_FORK	MAGIC_NO_COMPRESS_FORK	cookie::Flags::NO_COMPRESS_FORK
MAGIC_NODESC	MAGIC_NODESC	cookie::Flags::NODESC
MAGIC_NO_CHECK_COMPRESS	MAGIC_NO_CHECK_COMPRESS	cookie::Flags::NO_CHECK_COMPRESS
MAGIC_NO_CHECK_TAR	MAGIC_NO_CHECK_TAR	cookie::Flags::NO_CHECK_TAR
MAGIC_NO_CHECK_SOFT	MAGIC_NO_CHECK_SOFT	cookie::Flags::NO_CHECK_SOFT
MAGIC_NO_CHECK_APPTYPE	MAGIC_NO_CHECK_APPTYPE	cookie::Flags::NO_CHECK_APPTYPE
MAGIC_NO_CHECK_ELF	MAGIC_NO_CHECK_ELF	cookie::Flags::NO_CHECK_ELF
MAGIC_NO_CHECK_TEXT	MAGIC_NO_CHECK_TEXT	cookie::Flags::NO_CHECK_TEXT
MAGIC_NO_CHECK_CDF	MAGIC_NO_CHECK_CDF	cookie::Flags::NO_CHECK_CDF
MAGIC_NO_CHECK_CSV	MAGIC_NO_CHECK_CSV	cookie::Flags::NO_CHECK_CSV
MAGIC_NO_CHECK_TOKENS	MAGIC_NO_CHECK_TOKENS	cookie::Flags::NO_CHECK_TOKENS
MAGIC_NO_CHECK_ENCODING	MAGIC_NO_CHECK_ENCODING	cookie::Flags::NO_CHECK_ENCODING
MAGIC_NO_CHECK_JSON	MAGIC_NO_CHECK_JSON	cookie::Flags::NO_CHECK_JSON
MAGIC_NO_CHECK_SIMH	MAGIC_NO_CHECK_SIMH	cookie::Flags::NO_CHECK_SIMH
MAGIC_NO_CHECK_BUILTIN	MAGIC_NO_CHECK_BUILTIN	cookie::Flags::NO_CHECK_BUILTIN
MAGIC_SNPRINTB	❌	❌
MAGIC_NO_CHECK_ASCII	MAGIC_NO_CHECK_ASCII	❌
MAGIC_NO_CHECK_FORTRAN	MAGIC_NO_CHECK_FORTRAN	❌
MAGIC_NO_CHECK_TROFF	MAGIC_NO_CHECK_TROFF	❌
MAGIC_VERSION	❌	❌
struct magic_set	magic_set	cookie::Cookie
*magic_t	magic_t	cookie::Cookie
magic_open()	magic_open()	cookie::Cookie::open()
magic_close()	magic_close()	cookie::Cookie::drop()
magic_getpath()	magic_getpath()	❌
magic_file()	magic_file()	cookie::Cookie::file()
magic_descriptor()	magic_descriptor()	❌
magic_buffer()	magic_buffer()	cookie::Cookie::buffer()
magic_error()	magic_error()	cookie::Error
magic_getflags()	magic_getflags()	❌
magic_setflags()	magic_setflags()	cookie::Cookie::set_flags()
magic_version()	magic_version()	libmagic_version()
magic_load()	magic_load()	cookie::Cookie::load()
magic_load_buffers()	magic_load_buffers()	cookie::Cookie::load_buffers()
magic_compile()	magic_compile()	cookie::Cookie::compile()
magic_check()	magic_check()	cookie::Cookie::check()
magic_list()	magic_list()	cookie::Cookie::list()
magic_errno()	magic_errno()	cookie::Error
MAGIC_PARAM_INDIR_MAX	MAGIC_PARAM_INDIR_MAX	cookie::param::IndirMax
MAGIC_PARAM_NAME_MAX	MAGIC_PARAM_NAME_MAX	cookie::param::NameMax
MAGIC_PARAM_ELF_PHNUM_MAX	MAGIC_PARAM_ELF_PHNUM_MAX	cookie::param::ElfPhnumMax
MAGIC_PARAM_ELF_SHNUM_MAX	MAGIC_PARAM_ELF_SHNUM_MAX	cookie::param::ElfShnumMax
MAGIC_PARAM_ELF_NOTES_MAX	MAGIC_PARAM_ELF_NOTES_MAX	cookie::param::ElfNotesMax
MAGIC_PARAM_REGEX_MAX	MAGIC_PARAM_REGEX_MAX	cookie::param::RegexMax
MAGIC_PARAM_BYTES_MAX	MAGIC_PARAM_BYTES_MAX	cookie::param::BytesMax
MAGIC_PARAM_ENCODING_MAX	MAGIC_PARAM_ENCODING_MAX	cookie::param::EncodingMax
MAGIC_PARAM_ELF_SHSIZE_MAX	MAGIC_PARAM_ELF_SHSIZE_MAX	cookie::param::ElfShsizeMax
MAGIC_PARAM_MAGWARN_MAX	MAGIC_PARAM_MAGWARN_MAX	cookie::param::MagwarnMax
magic_setparam()	magic_setparam()	cookie::Cookie::set_param()
magic_getparam()	magic_getparam()	cookie::Cookie::get_param()

[robo9k]

MAGIC_NO_CHECK_ASCII has been renamed to MAGIC_NO_CHECK_TEXT - nothing to be done
MAGIC_NO_CHECK_FORTRAN, MAGIC_NO_CHECK_TROFF do nothing anymore - nothing to be done

[robo9k]

MAGIC_SNPRINTB gives names to flags so they can be read more easily, e.g. CLI
This is probably roughly equivalent to impl Display for cookie::Flags - nothing to be done

[robo9k]

magic_getpath returns the magic database locations and could be used to actually resolve cookie::DatabasePaths::default - this might be useful for users to know which implicit database files are used by libmagic, so .. something to be implemented eventually

[robo9k]

magic_descriptor is similar to magic_file but takes a file descriptor instead of a file path - this could probably be implemented using std::os::fd::AsFd but it's unclear how that'd work on e.g. Windows - so .. something to be implemented eventually

[robo9k]

magic_getflags is the inverse of magic_setflags and returns the current flags set on a cookie - this should be implemented

[robo9k]

magic_file can read from STDIN if NULL is passed as a filename - this could probably also be implemented in terms of magic_descriptor, so does not seem to be needed

[robo9k]

The MAGIC_VERSION build-time define is currently not provided by magic-sys, only the magic_version run-time function
This might be helpful for users to detect mismatches but also relatively complex (parse header, compile and link C object?) - not sure if this is worth it
Might be worth taking a look at how other -sys crates approach this, e.g. openssl
On the other hand this could also be used for "dynamic feature detection" instead of the current crate features that the users have to set themselves

See robo9k/rust-magic-sys#205

[robo9k]

In general, one should be able to search rustdoc for things from magic.h and find them via doc aliases
This has not been implemented for all things - so something that should be done

Everything not implemented yet or intentionally not provided should also be covered e.g. by the toplevel rustdoc
So this issue here becomes part of versioned documentation instead