You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
libisoburn/xorriso/xorriso.h

1477 lines
61 KiB

/* 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
12 years ago
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 */