|
|
|
|
|
|
|
/* xorriso - libisoburn higher level API which creates, loads, manipulates
|
|
|
|
and burns ISO 9660 filesystem images.
|
|
|
|
|
|
|
|
Copyright 2007-2012 Thomas Schmitt, <scdbackup@gmx.net>
|
|
|
|
|
|
|
|
Provided under GPL version 2 or later.
|
|
|
|
|
|
|
|
This file contains the public API of xorriso which covers all of its
|
|
|
|
operations.
|
|
|
|
|
|
|
|
An example of its usage is xorriso_main.c which checks version compatibility,
|
|
|
|
creates a xorriso object, initializes the libraries, and runs the command
|
|
|
|
interpreters of the API to constitute the command line oriented batch and
|
|
|
|
dialog tool xorriso.
|
|
|
|
|
|
|
|
Alternatively to command interpreters it is possible to run all options of
|
|
|
|
xorriso directly via the calls of the "Command API".
|
|
|
|
The "Problem Status and Message API" shall then be used to obtain the
|
|
|
|
text output of the options.
|
|
|
|
|
|
|
|
Mandatory calls are:
|
|
|
|
Xorriso_new(), Xorriso_startup_libraries(), Xorriso_destroy()
|
|
|
|
|
|
|
|
This architecture is fully public since version 0.5.8. From then on, new
|
|
|
|
features get marked by
|
|
|
|
@since major.minor.micro
|
|
|
|
If this mark is missing, then the feature was present before release 0.5.8.
|
|
|
|
|
|
|
|
Please note that struct XorrisO and its API calls are _not_ thread-safe in
|
|
|
|
general. It is not permissible to run two API calls on the same
|
|
|
|
XorrisO object concurrently.
|
|
|
|
The only exception is
|
|
|
|
Xorriso_fetch_outlists()
|
|
|
|
in order to learn about the ongoing text output of other API calls.
|
|
|
|
|
|
|
|
|
|
|
|
There is a lower level of API which consists of libisofs.h, libburn.h and
|
|
|
|
libisoburn.h. One should not mix those calls with the ones of xorriso.h .
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* Important: If you add a public API function then add its name to file
|
|
|
|
libisoburn/libisoburn.ver
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
#ifndef Xorriso_includeD
|
|
|
|
#define Xorriso_includeD yes
|
|
|
|
|
|
|
|
/** Opaque handle of the xorriso runtime context */
|
|
|
|
struct XorrisO;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/* This may be changed to Xorriso_GNU_xorrisO in order to create GNU xorriso
|
|
|
|
under GPLv3+ derived from above GPLv2+.
|
|
|
|
*/
|
|
|
|
#define Xorriso_libburnia_xorrisO yes
|
|
|
|
|
|
|
|
|
|
|
|
/* --------------------- Fundamental Management ------------------- */
|
|
|
|
|
|
|
|
|
|
|
|
/** These three release version numbers tell the revision of this header file
|
|
|
|
and of the API which it describes. They shall be memorized by applications
|
|
|
|
at build time.
|
|
|
|
@since 0.5.8
|
|
|
|
*/
|
|
|
|
#define Xorriso_header_version_majoR 1
|
|
|
|
#define Xorriso_header_version_minoR 2
|
|
|
|
#define Xorriso_header_version_micrO 5
|
|
|
|
|
|
|
|
|
|
|
|
/** If needed: Something like ".pl01" to indicate a bug fix. Normally empty.
|
|
|
|
@since 0.5.8
|
|
|
|
*/
|
|
|
|
#define Xorriso_program_patch_leveL ""
|
|
|
|
|
|
|
|
|
|
|
|
/** Obtain the three release version numbers of the library. These are the
|
|
|
|
numbers encountered by the application when linking with libisoburn,
|
|
|
|
i.e. possibly not before run time.
|
|
|
|
Better do not base the fundamental compatibility decision of an application
|
|
|
|
on these numbers. For a reliable check use Xorriso__is_compatible().
|
|
|
|
@since 0.5.8
|
|
|
|
@param major The maturity version (0 for now, as we are still learning)
|
|
|
|
@param minor The development goal version.
|
|
|
|
@param micro The development step version. This has an additional meaning:
|
|
|
|
|
|
|
|
Pare numbers indicate a version with frozen API. I.e. you can
|
|
|
|
rely on the same set of features to be present in all
|
|
|
|
published releases with that major.minor.micro combination.
|
|
|
|
Features of a pare release will stay available and ABI
|
|
|
|
compatible as long as the SONAME of libisoburn stays "1".
|
|
|
|
Currently there are no plans to ever change the SONAME.
|
|
|
|
|
|
|
|
Odd numbers indicate that API upgrades are in progress.
|
|
|
|
I.e. new features might be already present or they might
|
|
|
|
be still missing. Newly introduced features may be changed
|
|
|
|
incompatibly or even be revoked before release of a pare
|
|
|
|
version.
|
|
|
|
So micro revisions {1,3,5,7,9} should never be used for
|
|
|
|
dynamic linking unless the proper library match can be
|
|
|
|
guaranteed by external circumstances.
|
|
|
|
|
|
|
|
@return 1 success, <=0 might in future become an error indication
|
|
|
|
*/
|
|
|
|
void Xorriso__version(int *major, int *minor, int *micro);
|
|
|
|
|
|
|
|
|
|
|
|
/** Check whether all features of header file xorriso.h from the given
|
|
|
|
major.minor.micro revision triple can be delivered by the library version
|
|
|
|
which is performing this call.
|
|
|
|
if (! Xorriso__is_compatible(Xorriso_header_version_majoR,
|
|
|
|
Xorriso_header_version_minoR,
|
|
|
|
Xorriso_header_version_micrO, 0))
|
|
|
|
...refuse to start the program with this dynamic library version...
|
|
|
|
@since 0.5.8
|
|
|
|
@param major obtained at build time
|
|
|
|
@param minor obtained at build time
|
|
|
|
@param micro obtained at build time
|
|
|
|
@param flag Bitfield for control purposes. Unused yet. Submit 0.
|
|
|
|
@return 1= library can work for caller
|
|
|
|
0= library is not usable in some aspects. Caller must restrict
|
|
|
|
itself to an earlier API version or must not use this library
|
|
|
|
at all.
|
|
|
|
*/
|
|
|
|
int Xorriso__is_compatible(int major, int minor, int micro, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Get the patch level text (e.g. "" or ".pl01") of the program code.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return readonly character string
|
|
|
|
*/
|
|
|
|
char *Xorriso__get_patch_level_text(int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Choose how Xorriso_startup_libraries() and the XorrisO object shall
|
|
|
|
prepare for eventual signals.
|
|
|
|
@param behavior Default is behavior 1.
|
|
|
|
0= no own signal handling. The main application has to do
|
|
|
|
that. Do not start burn runs without any handling !
|
|
|
|
1= use libburn signal handler. Most time with action
|
|
|
|
0. During writing, formatting, blanking: 0x30.
|
|
|
|
Only usable with a single xorriso object.
|
|
|
|
2= Enable system default reaction on all signals
|
|
|
|
@since 1.0.9
|
|
|
|
3= Try to ignore nearly all signals
|
|
|
|
@since 1.0.9
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return <= 0 is error, >0 is success
|
|
|
|
*/
|
|
|
|
int Xorriso__preset_signal_behavior(int behavior, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Mandatory call:
|
|
|
|
Create a new xorriso object and tell it the program name to be used
|
|
|
|
with messages and for decision of special behavior.
|
|
|
|
@param xorriso returns the newly created XorrisO object
|
|
|
|
@param progname typically argv[0] of main(). Some leafnames of the progname
|
|
|
|
path have special meaning and trigger special behavior:
|
|
|
|
"osirrox" allows image-to-disk copying: -osirrox "on"
|
|
|
|
"xorrisofs" activates -as "mkisofs" emulation from start
|
|
|
|
"genisofs" alias of "xorrisofs"
|
|
|
|
"mkisofs" alias of "xorrisofs"
|
|
|
|
"genisoimage" alias of "xorrisofs"
|
|
|
|
"xorrecord" activates -as "cdrecord" emulation from start
|
|
|
|
"cdrecord" alias of "xorrecord"
|
|
|
|
"wodim" alias of "xorrecord"
|
|
|
|
"cdrskin" alias of "xorrecord"
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return >0 success , <=0 failure, no object created
|
|
|
|
*/
|
|
|
|
int Xorriso_new(struct XorrisO ** xorriso, char *progname, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Note: Between Xorriso_new() and the next call Xorriso_startup_libraries()
|
|
|
|
there may be called the special command interpreter
|
|
|
|
Xorriso_prescan_args().
|
|
|
|
The other command interpreters may be used only after
|
|
|
|
Xorriso_startup_libraries(). The same restriction applies to the
|
|
|
|
calls of the Command API further below.
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/* Mandatory call:
|
|
|
|
It has to be made before calling any function listed below this point.
|
|
|
|
Only exception is the special command interpreter Xorriso_prescan_args().
|
|
|
|
|
|
|
|
Make global library initializations.
|
|
|
|
This must be done with the first xorriso object that gets created and
|
|
|
|
with the first xorriso object that gets created after Xorriso_destroy(,1).
|
|
|
|
@param xorriso The context object.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return <=0 error , >0 success
|
|
|
|
*/
|
|
|
|
int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Note: After library startup, you may run Command Interpreters or call
|
|
|
|
functions from the Command API.
|
|
|
|
|
|
|
|
Wenn all desired activities are done, you may check whether there are
|
|
|
|
uncommited changes pending, compute an exit value, destroy the XorrisO
|
|
|
|
object, and exit your program.
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/* Inquire whether option -commit would make sense.
|
|
|
|
@param xorriso The context object to inquire.
|
|
|
|
@param flag @since 0.6.6
|
|
|
|
bit0= do not return 1 if -as mkisofs -print-size was
|
|
|
|
performed on the current image.
|
|
|
|
@return 0= -commit would have nothing to do
|
|
|
|
1= a new image session would emerge at -commit
|
|
|
|
*/
|
|
|
|
int Xorriso_change_is_pending(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Compute the exit value from the recorded maximum event severity.
|
|
|
|
@param xorriso The context object to inquire.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return The computed exit value
|
|
|
|
*/
|
|
|
|
int Xorriso_make_return_value(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Mandatory call:
|
|
|
|
Destroy xorriso object when it is no longer needed.
|
|
|
|
@param xorriso The context object to destroy. *xorriso will become NULL.
|
|
|
|
@param flag bit0= Perform global library shutdown.
|
|
|
|
Use only with last xorriso object to be destroyed.
|
|
|
|
@return <=0 error, >0 success
|
|
|
|
*/
|
|
|
|
int Xorriso_destroy(struct XorrisO **xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* --------------------- Command Interpreters ------------------- */
|
|
|
|
|
|
|
|
|
|
|
|
/* This special interpreter may be called between Xorriso_new() and
|
|
|
|
Xorriso_startup_libraries(). It interprets certain commands which shall
|
|
|
|
get into effect before the libraries get initialized:
|
|
|
|
-abort_on , -report_about , -return_with , -list_delimiter ,
|
|
|
|
-scsi_log , -signal_handling
|
|
|
|
This is the only occasion where command -x has an effect:
|
|
|
|
-x
|
|
|
|
Some commands get executed only if they are the only command in argv:
|
|
|
|
-prog_help , -help
|
|
|
|
The following is recognized only if it is the first of all arguments:
|
|
|
|
-no_rc
|
|
|
|
Some get examined for the need to redirect stdout messages:
|
|
|
|
-dev , -outdev , -indev , -as
|
|
|
|
Commands -list_delimiter and -add_plainly get into effect during this
|
|
|
|
call. But their setting at begin of the call gets restored before the
|
|
|
|
call returns.
|
|
|
|
@param xorriso The context object in which to perform the commands.
|
|
|
|
@param argc Number of arguments.
|
|
|
|
@param argv The arguments. argv[0] contains the program name.
|
|
|
|
argv[1] to argv[argc-1] contain commands and parameters.
|
|
|
|
@param idx Argument cursor. When this function is called, *idx must
|
|
|
|
be at least 1, argv[*idx] must be a command.
|
|
|
|
*idx will iterate over commands and parameters until this
|
|
|
|
function aborts or until argc is reached.
|
|
|
|
@param flag bit0= do not interpret argv[1]
|
|
|
|
bit1= produce FAILURE events on unknown commands
|
|
|
|
@since 1.1.0
|
|
|
|
@return <0 error
|
|
|
|
0 end program
|
|
|
|
1 ok, go on
|
|
|
|
*/
|
|
|
|
int Xorriso_prescan_args(struct XorrisO *xorriso, int argc, char **argv,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Read and interpret commands from eventual startup files as listed in
|
|
|
|
man xorriso.
|
|
|
|
@param xorriso The context object in which to perform the commands.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return <=0 = error
|
|
|
|
1 = success
|
|
|
|
3 = end program run (e.g. because command -end was encountered)
|
|
|
|
*/
|
|
|
|
int Xorriso_read_rc(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Check whether program arguments shall be backslash decoded. If so, then
|
|
|
|
replace *argv by a new argument vector. The old one will not be freed
|
|
|
|
by this call. If it is dynamic memory then you need to keep a copy of
|
|
|
|
the pointer and free it yourself after this call.
|
|
|
|
@param xorriso The context object
|
|
|
|
@param argc Number of arguments.
|
|
|
|
@param argv The arguments. (*argv)[0] contains the program name.
|
|
|
|
(*argv)[1] to (*argv)[argc-1] contain commands and parameters
|
|
|
|
If argv after the call differs from argv before the call,
|
|
|
|
then one should dispose it later by:
|
|
|
|
Xorriso__dispose_words(argc, argv);
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return <= 0 error , > 0 success
|
|
|
|
*/
|
|
|
|
int Xorriso_program_arg_bsl(struct XorrisO *xorriso, int argc, char ***argv,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Interpret argv as xorriso command options and their parameters.
|
|
|
|
(An alternative is to call functions of the options API directly and to
|
|
|
|
perform own error status evaluation. See below: Command API.)
|
|
|
|
After the first command and its parameters there may be more commands and
|
|
|
|
parameters. All parameters must be given in the same call as their command.
|
|
|
|
@since 1.2.2:
|
|
|
|
Commands may get arranged in a sequence that is most likely to make sense.
|
|
|
|
E.g. image loading settings before drive aquiration, then commands for
|
|
|
|
adding files, then settings for writing, then writing.
|
|
|
|
This feature may be enabled by command "-x" in Xorriso_prescan_args()
|
|
|
|
or by parameter flag of this call.
|
|
|
|
@param xorriso The context object in which to perform the commands.
|
|
|
|
@param argc Number of arguments.
|
|
|
|
@param argv The arguments. argv[0] contains the program name.
|
|
|
|
argv[1] to argv[argc-1] contain commands and parameters.
|
|
|
|
@param idx Argument cursor. When this function is called, *idx must
|
|
|
|
be at least 1, argv[*idx] must be a command.
|
|
|
|
*idx will iterate over commands and parameters until this
|
|
|
|
function aborts, or until argc is reached, or only once if
|
|
|
|
flag bit2 is set.
|
|
|
|
@param flag bit0= reserved. Indicates recursion. Submit 0.
|
|
|
|
bit1= Indicates that these are the main() program start
|
|
|
|
arguments. This enables their use with emulations
|
|
|
|
which where set with Xorriso_new(), or argument
|
|
|
|
arranging.
|
|
|
|
bit2= Only execute the one command argv[*idx] and advance
|
|
|
|
*idx to the next command if sucessful. Then return.
|
|
|
|
This prevents any argument arranging.
|
|
|
|
@since 1.2.2
|
|
|
|
bit3= With bit1 and not bit2:
|
|
|
|
Enable argument arranging as with
|
|
|
|
Xorriso_prescan_args() and command "-x".
|
|
|
|
@since 1.2.2
|
|
|
|
bit4= With bit1:
|
|
|
|
Surely disable argument arranging.
|
|
|
|
@since 1.2.2
|
|
|
|
@return <=0 = error
|
|
|
|
1 = success
|
|
|
|
2 = problem event ignored
|
|
|
|
3 = end program run (e.g. because command -end was encountered)
|
|
|
|
*/
|
|
|
|
int Xorriso_interpreter(struct XorrisO *xorriso,
|
|
|
|
int argc, char **argv, int *idx, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Parse a command line into words and use them as argv for a call of
|
|
|
|
Xorriso_interpreter(). Put out some info lines about the outcome.
|
|
|
|
@param xorriso The context object in which to perform the commands.
|
|
|
|
@param line A text of one or more words according to man xorriso
|
|
|
|
paragraph "Command processing" up to and including
|
|
|
|
"Backslash Interpretation".
|
|
|
|
@param flag bit0 to bit15 are forwarded to Xorriso_interpreter()
|
|
|
|
bit16= no pageing of info lines
|
|
|
|
bit17= print === bar even if xorriso->found<0
|
|
|
|
@return see return of Xorriso_interpreter()
|
|
|
|
*/
|
|
|
|
int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Parse a text line into words. This parsing obeys the same rules as
|
|
|
|
command line parsing but allows to skip a prefix, to use a user provided
|
|
|
|
set of separator characters, and to restrict the number of parsed words.
|
|
|
|
@since 1.2.6
|
|
|
|
@param xorriso The context object which provides settings for parsing
|
|
|
|
@param line A text of one or more words according to man xorriso
|
|
|
|
paragraph "Command processing" up to and including
|
|
|
|
"Backslash Interpretation".
|
|
|
|
@param prefix If not empty then the line will only be parsed if it
|
|
|
|
begins by the prefix text. Parsing will then begin after
|
|
|
|
the end of the prefix.
|
|
|
|
If the prefix does not match, then 0 will be returned
|
|
|
|
in *argc, argv will be NULL, and the return value will
|
|
|
|
be 2.
|
|
|
|
@param separators If not empty this overrides the default list of word
|
|
|
|
separating characters. Default set is the one of
|
|
|
|
isspace(3).
|
|
|
|
@param max_words If not 0: Maximum number of words to parse. If there
|
|
|
|
remains line text after the last parsed word and its
|
|
|
|
following separators, then this remainder is copied
|
|
|
|
unparsed into a final result word. In this case *argc
|
|
|
|
will be larger than max_words by one. Note that trailing
|
|
|
|
separators are considered to be followed by an empty
|
|
|
|
word.
|
|
|
|
@param argc Will return the number of allocated and filled word
|
|
|
|
strings.
|
|
|
|
@param argv Will return the array of word strings.
|
|
|
|
Do not forget to dispose the allocated memory by a
|
|
|
|
call to Xorriso__dispose_words().
|
|
|
|
@param flag Bitfield for control purposes
|
|
|
|
bit0= Override setting of -backslash_codes
|
|
|
|
bit1-4= With bit1: backslash behavior
|
|
|
|
0= off
|
|
|
|
1= in_double_quotes
|
|
|
|
2= in_quotes
|
|
|
|
3= with_quoted_input resp. on
|
|
|
|
bit5= Prepend the program name as (*argv)[0], so that
|
|
|
|
*argv is suitable for Xorriso_interpreter()
|
|
|
|
and other calls which expect this.
|
|
|
|
bit6= Issue failure message in case of return 0
|
|
|
|
@return <=0 means error and invalidity of *argv:
|
|
|
|
0 = Input format error. E.g. bad quotation mark.
|
|
|
|
-1 = Lack of resources. E.g. memory.
|
|
|
|
>0 means success but not necessarily a valid result:
|
|
|
|
1 = Result in argc and argv is valid (but may
|
|
|
|
be empty by argc == 0, argv == NULL).
|
|
|
|
2 = Line did not match prefix. Result is invalid
|
|
|
|
and empty.
|
|
|
|
*/
|
|
|
|
int Xorriso_parse_line(struct XorrisO *xorriso, char *line,
|
|
|
|
char *prefix, char *separators, int max_words,
|
|
|
|
int *argc, char ***argv, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Dispose a list of strings as allocated by Xorriso_parse_line() or
|
|
|
|
Xorriso_program_arg_bsl().
|
|
|
|
@since 1.2.6
|
|
|
|
@param argc A pointer to the number of allocated and filled word
|
|
|
|
strings. *argc will be set to 0 by this call.
|
|
|
|
@param argv A pointer to the array of word strings.
|
|
|
|
*argv will be set to NULL by this call.
|
|
|
|
*/
|
|
|
|
void Xorriso__dispose_words(int *argc, char ***argv);
|
|
|
|
|
|
|
|
|
|
|
|
/* Enter xorriso command line dialog mode, using libreadline if configured
|
|
|
|
at build time and not disabled at run time.
|
|
|
|
This call returns immediately if not option -dialog "on" was performed
|
|
|
|
before.
|
|
|
|
@param xorriso The context object in which to perform the commands.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return <=0 error, 1= dialog mode ended normally ,
|
|
|
|
3= dialog mode ended normally,interpreter asks to end program
|
|
|
|
*/
|
|
|
|
int Xorriso_dialog(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* --------------------- Problem Status and Message API ------------------- */
|
|
|
|
|
|
|
|
|
|
|
|
/** Submit a problem message to the xorriso problem reporting and handling
|
|
|
|
system. This will eventually increase problem status rank, which may
|
|
|
|
at certain stages in the program be pardoned and reset to 0.
|
|
|
|
The pardon is governed by Xorriso_option_abort_on() and by the anger
|
|
|
|
of the affected program part. If no pardon has been given, then the problem
|
|
|
|
status reaches the caller of option functions.
|
|
|
|
Problem status should be inquired by Xorriso_eval_problem_status() and be
|
|
|
|
reset before next option execution by Xorriso_set_problem_status().
|
|
|
|
The problem status itself does not cause the failure of option functions.
|
|
|
|
But in case of failures for other reasons, a remnant overly severe problem
|
|
|
|
status can cause overly harsh program reactions.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param error_code The unique error code of your message.
|
|
|
|
Submit 0 if you do not have reserved error codes within
|
|
|
|
the libburnia project.
|
|
|
|
@param msg_text Not more than 8196 characters of message text.
|
|
|
|
A final newline character gets appended automatically.
|
|
|
|
@param os_errno Eventual errno related to the message. Submit 0 if
|
|
|
|
the message is not related to a operating system error.
|
|
|
|
@param severity One of "ABORT", "FATAL", "FAILURE", "MISHAP", "SORRY",
|
|
|
|
"WARNING", "HINT", "NOTE", "UPDATE", "DEBUG".
|
|
|
|
Defaults to "FATAL".
|
|
|
|
@param flag Bitfield for control purposes
|
|
|
|
bit0= use pager (as with result)
|
|
|
|
bit1= permission to suppress output
|
|
|
|
@return 1 if message was delivered, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_msgs_submit(struct XorrisO *xorriso,
|
|
|
|
int error_code, char msg_text[], int os_errno,
|
|
|
|
char severity[], int flag);
|
|
|
|
|
|
|
|
/** Alternative call interface of Xorriso_msgs_submit with void* instead
|
|
|
|
of struct XorrisO*
|
|
|
|
*/
|
|
|
|
int Xorriso_msgs_submit_void(void *xorriso,
|
|
|
|
int error_code, char msg_text[], int os_errno,
|
|
|
|
char severity[], int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Evaluate an advise whether to abort or whether to go on with option
|
|
|
|
processing. This should be called after any option function was processed.
|
|
|
|
It updates the problem status by processing the library message queues
|
|
|
|
and then it uses this status and the submitted return value of the
|
|
|
|
option function to evaluate the situation.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param ret The return value of the previously called option function
|
|
|
|
@param flag bit0= do not issue own event messages
|
|
|
|
bit1= take xorriso->request_to_abort as reason for abort
|
|
|
|
@return Gives the advice:
|
|
|
|
2= pardon was given, go on
|
|
|
|
1= no problem, go on
|
|
|
|
0= function failed but xorriso would not abort, go on
|
|
|
|
<0= do abort
|
|
|
|
-1 = due to xorriso->problem_status
|
|
|
|
or due to ret<0
|
|
|
|
-2 = due to xorriso->request_to_abort
|
|
|
|
*/
|
|
|
|
int Xorriso_eval_problem_status(struct XorrisO *xorriso, int ret, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Set the current problem status of the xorriso handle.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param severity A severity text. Empty text resets to "No Problem".
|
|
|
|
@param flag Unused yet. Submit 0.
|
|
|
|
@return <=0 failure (e.g. wrong severity text), 1 success.
|
|
|
|
*/
|
|
|
|
int Xorriso_set_problem_status(struct XorrisO *xorriso, char *severity,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* The next two functions are part of Xorriso_eval_problem_status().
|
|
|
|
You may use them to build an own advisor function.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/** Obtain the current problem status of the xorriso handle.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param severity The severity text matching the current problem status
|
|
|
|
@param flag Unused yet. Submit 0.
|
|
|
|
@return The severity rank number. 0= no problem occured.
|
|
|
|
*/
|
|
|
|
int Xorriso_get_problem_status(struct XorrisO *xorriso, char severity[80],
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Forward any pending messages from the library message queues to the
|
|
|
|
xorriso message system which puts out on info channel. This registers
|
|
|
|
the severity of the library events like the severity of a message submitted
|
|
|
|
via Xorriso_msgs_submit().
|
|
|
|
xorriso sets the message queues of the libraries to queuing "ALL".
|
|
|
|
Many inner functions of xorriso call Xorriso_process_msg_queues() on their
|
|
|
|
own because they expect library output pending. Nevertheless, a loop of
|
|
|
|
xorriso option calls should either call Xorriso_eval_problem_status() or
|
|
|
|
Xorriso_process_msg_queues() with each cycle.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param flag Unused yet. Submit 0.
|
|
|
|
@return 1 on success, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_process_msg_queues(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Write a message for option -errfile_log.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param error_code The unique error code of your message.
|
|
|
|
Submit 0 if you do not have reserved error codes within
|
|
|
|
the libburnia project.
|
|
|
|
@param msg_text Not more than 8196 characters of message text.
|
|
|
|
@param os_errno Eventual errno related to the message. Submit 0 if
|
|
|
|
the message is not related to a operating system error.
|
|
|
|
@param flag bit0-7= meaning of msg_text
|
|
|
|
( 0= ERRFILE path , for internal use mainly )
|
|
|
|
1= mark line text (only to be put out if enabled)
|
|
|
|
@return <=0 error , >0 success
|
|
|
|
*/
|
|
|
|
int Xorriso_process_errfile(struct XorrisO *xorriso,
|
|
|
|
int error_code, char msg_text[], int os_errno,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* The outlist stack allows to redirect the info and result messages from
|
|
|
|
their normal channels into a pair of string lists which can at some
|
|
|
|
later time be retrieved by the application.
|
|
|
|
These redirection caches can be stacked to allow stacked applications.
|
|
|
|
xorriso itself uses them for internal purposes.
|
|
|
|
|
|
|
|
The call Xorriso_start_msg_watcher() starts a concurrent thread which
|
|
|
|
uses outlists to collect messages and to hand them over by calling
|
|
|
|
application provided functions.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* A list item able of forming double chained lists */
|
|
|
|
struct Xorriso_lsT;
|
|
|
|
|
|
|
|
/** Maximum number of stacked redirections */
|
|
|
|
#define Xorriso_max_outlist_stacK 32
|
|
|
|
|
|
|
|
/** Enable a new redirection of info and/or result channel. The normal message
|
|
|
|
output and eventual older redirections will not see new messages until
|
|
|
|
the redirection is ended by a call to Xorriso_pull_outlists() with the
|
|
|
|
stack_handle value returned by this call.
|
|
|
|
Redirected output is not written to the files of Xorriso_option_logfile()
|
|
|
|
and the Xorriso_option_pkt_output() protocol will not be applied.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param stack_handle returns an id number which is unique as long as
|
|
|
|
its redirection is stacked. Do not interpret it and
|
|
|
|
do not use it after its redirection was pulled from
|
|
|
|
the stack.
|
|
|
|
@param flag Bitfield for control purposes
|
|
|
|
bit0= redirect result channel
|
|
|
|
bit1= redirect info channel
|
|
|
|
If bit0 and bit1 are 0, both channels get redirected.
|
|
|
|
@return 1 on success, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_push_outlists(struct XorrisO *xorriso, int *stack_handle,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Obtain the currently collected text messages of redirected info and
|
|
|
|
result channel.
|
|
|
|
The messages are handed out as two lists. Both lists have to be disposed
|
|
|
|
via Xorriso_lst_destroy_all() when they are no longer needed.
|
|
|
|
The message lists are either NULL or represented by their first
|
|
|
|
Xorriso_lsT item.
|
|
|
|
|
|
|
|
This call is safe for being used by a concurrent thread while a
|
|
|
|
xorriso API call is being executed on the same struct XorrisO.
|
|
|
|
In such a situation, it should not be used with high frequency in order
|
|
|
|
not to hamper the ongoing xorriso operation by blocking its message
|
|
|
|
output facility. A hundred times per second should be enough.
|
|
|
|
|
|
|
|
@since 1.2.6
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param stack_handle An id number returned by Xorriso_push_outlists()
|
|
|
|
and not yet revoked by Xorriso_pull_outlists().
|
|
|
|
Submit -1 to address the most recent valid id.
|
|
|
|
@param result_list Result and mark messages (usually directed to stdout)
|
|
|
|
@param info_list Info and mark messages (usually directed to stderr)
|
|
|
|
@param flag Bitfield for control purposes
|
|
|
|
bit0= fetch result channel
|
|
|
|
bit1= fetch info channel
|
|
|
|
If bit0 and bit1 are 0, both channels get fetched.
|
|
|
|
@return 1 on success, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_fetch_outlists(struct XorrisO *xorriso, int stack_handle,
|
|
|
|
struct Xorriso_lsT **result_list,
|
|
|
|
struct Xorriso_lsT **info_list, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Disable the redirection given by stack_handle. If it was the current
|
|
|
|
receiver of messages then switch output to the next older redirection
|
|
|
|
resp. to the normal channels if no redirections are stacked any more.
|
|
|
|
The messages collected by the disabled redirection are handed out as
|
|
|
|
two lists. Both lists have to be disposed via Xorriso_lst_destroy_all()
|
|
|
|
when they are no longer needed.
|
|
|
|
The message lists are either NULL or represented by their first
|
|
|
|
Xorriso_lsT item.
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param stack_handle An id number returned by Xorriso_push_outlists()
|
|
|
|
and not yet revoked by Xorriso_pull_outlists().
|
|
|
|
This handle is invalid after the call.
|
|
|
|
Submit -1 to address the most recent valid id.
|
|
|
|
@param result_list Result and mark messages (usually directed to stdout)
|
|
|
|
@param info_list Info and mark messages (usually directed to stderr)
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return 1 on success, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_pull_outlists(struct XorrisO *xorriso, int stack_handle,
|
|
|
|
struct Xorriso_lsT **result_list,
|
|
|
|
struct Xorriso_lsT **info_list, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Redirect output by Xorriso_push_outlists() and start a thread which
|
|
|
|
fetches this output and performs a call of a given function with each
|
|
|
|
message that is obtained.
|
|
|
|
@since 1.2.6
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param result_handler Pointer to the function which shall be called with
|
|
|
|
each result message. A NULL pointer causes output
|
|
|
|
to be directed to stdout.
|
|
|
|
@param result_handle The first argument of (*result_handler)(). It shall
|
|
|
|
point to a memory object that knows all necessary
|
|
|
|
external parameters for running (*result_handler)().
|
|
|
|
Submit NULL if result_handler is NULL.
|
|
|
|
@param info_handler Pointer to the function which shall be called with
|
|
|
|
each info message. A NULL pointer causes output to
|
|
|
|
be directed to stderr resp. to -as mkisofs -log-file.
|
|
|
|
@param info_handle The first argument of (*info_handler)(). It shall
|
|
|
|
point to a memory object that knows all necessary
|
|
|
|
external parameters for running (*info_handler)().
|
|
|
|
Submit NULL if info_handler is NULL.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return 1 on success, <=0 if failure (e.g. there is already
|
|
|
|
a watcher active)
|
|
|
|
*/
|
|
|
|
int Xorriso_start_msg_watcher(struct XorrisO *xorriso,
|
|
|
|
int (*result_handler)(void *handle, char *text),
|
|
|
|
void *result_handle,
|
|
|
|
int (*info_handler)(void *handle, char *text),
|
|
|
|
void *info_handle,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Revoke output redirection by Xorriso_start_msg_watcher() and end the
|
|
|
|
watcher thread. If text messages are delivered when Xorriso_pull_outlists()
|
|
|
|
is called, then they get put out through the active handler functions.
|
|
|
|
@since 1.2.6
|
|
|
|
@param xorriso The environment handle
|
|
|
|
@param flag Bitfield for control purposes:
|
|
|
|
bit0= do not issue SORRY message if no message
|
|
|
|
watcher is active
|
|
|
|
@return 1 on success, <=0 if failure
|
|
|
|
*/
|
|
|
|
int Xorriso_stop_msg_watcher(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Obtain the text message from the current list item.
|
|
|
|
@param entry The current list item
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return Pointer to the text content of the list item.
|
|
|
|
This pointer does not have to be freed.
|
|
|
|
*/
|
|
|
|
char *Xorriso_lst_get_text(struct Xorriso_lsT *entry, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Obtain the address of the next item in the chain of messages.
|
|
|
|
An iteration over the output of Xorriso_pull_outlists() starts at the
|
|
|
|
returned result_list resp. info_list and ends when this function returns
|
|
|
|
NULL.
|
|
|
|
@param entry The current list item
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return Pointer to the next list item or NULL if end of list.
|
|
|
|
This pointer does not have to be freed.
|
|
|
|
*/
|
|
|
|
struct Xorriso_lsT *Xorriso_lst_get_next(struct Xorriso_lsT *entry, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Obtain the address of the previous item in the chain of messages.
|
|
|
|
@param entry The current list item
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return Pointer to the previous list item or NULL if start of list.
|
|
|
|
This pointer does not have to be freed.
|
|
|
|
*/
|
|
|
|
struct Xorriso_lsT *Xorriso_lst_get_prev(struct Xorriso_lsT *entry, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/** Destroy all list items which are directly or indirectly connected to
|
|
|
|
the given link item.
|
|
|
|
All pointers obtained by Xorriso_lst_get_text() become invalid by this.
|
|
|
|
Apply this to each of the two list handles obtained by
|
|
|
|
Xorriso_pull_outlists() when the lists are no longer needed.
|
|
|
|
@param lstring *lstring will be freed and set to NULL.
|
|
|
|
It is not dangerous to submit a pointer to a NULL-pointer.
|
|
|
|
@param flag unused yet, submit 0
|
|
|
|
@return -1= lstring was NULL (i.e. wrong use of this call),
|
|
|
|
0= *lstring was already NULL,
|
|
|
|
1= item actually disposed
|
|
|
|
*/
|
|
|
|
int Xorriso_lst_destroy_all(struct Xorriso_lsT **lstring, int flag);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/* ---------------------------- Command API ------------------------ */
|
|
|
|
/* See man 1 xorriso for explanation of the particular commands */
|
|
|
|
/*
|
|
|
|
Before each call to a command function, there should happen:
|
|
|
|
Xorriso_set_problem_status() with empty severity text.
|
|
|
|
|
|
|
|
After each call to a command function, there should happen:
|
|
|
|
Xorriso_eval_problem_status()
|
|
|
|
One should follow its eventual advice to abort.
|
|
|
|
|
|
|
|
Commands with a varying number of arguments get then passed like
|
|
|
|
Xorriso_interpreter(). E.g.:
|
|
|
|
int Xorriso_option_add(struct XorrisO *xorriso, int argc, char **argv,
|
|
|
|
int *idx, int flag);
|
|
|
|
The command functions will begin to read the arguments at position *idx
|
|
|
|
and will see the list end either at the next argv which contains the
|
|
|
|
-list_delimiter text or at argv[argc-1].
|
|
|
|
After the call, *idx will be the index of the first not yet interpreted
|
|
|
|
argv.
|
|
|
|
|
|
|
|
Do not set any flag bits which are not described by "@param flag".
|
|
|
|
I.e. if flag is not mentioned, then submit 0.
|
|
|
|
Yet undefined flag bits might get a meaning in future. Unset bits will
|
|
|
|
then produce the traditional behavior, whereas set bits might bring
|
|
|
|
surprises to inadverted callers.
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/* Command -abort_on */
|
|
|
|
int Xorriso_option_abort_on(struct XorrisO *xorriso, char *severity, int flag);
|
|
|
|
|
|
|
|
/* Command -abstract_file */
|
|
|
|
/* @since 0.6.0 */
|
|
|
|
int Xorriso_option_abstract_file(struct XorrisO *xorriso, char *name,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
/* Command -acl "on"|"off" */
|
|
|
|
int Xorriso_option_acl(struct XorrisO *xorriso, char *mode, int flag);
|
|
|
|
|
|
|
|
/* Command -add */
|
|
|
|
/* @param flag bit0=do not report the added item
|
|
|
|
bit1=do not reset pacifier, no final pacifier message
|
|
|
|
*/
|
|
|
|
int Xorriso_option_add(struct XorrisO *xorriso, int argc, char **argv,
|
|
|
|
int *idx, int flag);
|
|
|
|
|
|
|
|
/* Command -add_plainly "on"|"off" */
|
|
|
|
int Xorriso_option_add_plainly(struct XorrisO *xorriso, char *mode,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
|
|
|
|
/* Command -alter_date, alter_date_r */
|
|
|
|
/* @param flag bit0=recursive (-alter_date_r)
|
|
|
|
*/
|
|
|
|
int Xorriso_option_alter_date(struct XorrisO *xorriso,
|
|
|
|
char *time_type, char *timestring,
|
|
|
|
int argc, char **argv, int *idx, int flag);
|
|
|
|
|
|
|
|
/* Command -append_partition */
|
|
|
|
/* @since 0.6.4 */
|
|
|
|
int Xorriso_option_append_partition(struct XorrisO *xorriso, char *partno_text,
|
|
|
|
char *type_text, char *image_path, int flag);
|
|
|
|
|
|
|
|
/* Command -application_id */
|
|
|
|
int Xorriso_option_application_id(struct XorrisO *xorriso, char *name,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
/* Command -as */
|
|
|
|
/* @param flag bit0=do not report the added item
|
|
|
|
bit1=do not reset pacifier, no final pacifier message
|
|
|
|
*/
|
|
|
|
int Xorriso_option_as(struct XorrisO *xorriso, int argc, char **argv,
|
|
|
|
int *idx, int flag);
|
|
|
|
|
|
|
|
/* Command -assert_volid */
|
|
|
|
int Xorriso_option_assert_volid(struct XorrisO *xorriso, char *pattern,
|
|
|
|
char *severity, int flag);
|
|
|
|
|
|
|
|
/* Command -auto_charset "on"|"off" */
|
|
|
|
int Xorriso_option_auto_charset(struct XorrisO *xorriso, char *mode, int flag);
|
|
|
|
|
|
|
|
/* Command -backslash_codes */
|
|
|
|
int Xorriso_option_backslash_codes(struct XorrisO *xorriso, char *mode,
|
|
|
|
int flag);
|
|
|
|
|
|
|
|
/* Command -ban_stdio_write */
|
|
|
|
int Xorriso_option_ban_stdio_write(struct XorrisO *xorriso, int flag);
|
|
|
|
|
|
|
|
/* Command -biblio_file */
|
|
|
|
/* @since 0.6.0 */
|
|
|