diff --git a/xorriso/base_obj.c b/xorriso/base_obj.c index b019d6ac..671a0c21 100644 --- a/xorriso/base_obj.c +++ b/xorriso/base_obj.c @@ -38,9 +38,22 @@ static int Xorriso_signal_behavioR= 1; -char *Xorriso__get_version_text(int flag) +void Xorriso__version(int *major, int *minor, int *micro) { - return(Xorriso_program_versioN); + *major= Xorriso_header_version_majoR; + *minor= Xorriso_header_version_minoR; + *micro= Xorriso_header_version_micrO; +} + + +int Xorriso__is_compatible(int major, int minor, int micro, int flag) +{ + int own_major, own_minor, own_micro; + + Xorriso__version(&own_major, &own_minor, &own_micro); + return(own_major > major || + (own_major == major && (own_minor > minor || + (own_minor == minor && own_micro >= micro)))); } diff --git a/xorriso/opts_p_z.c b/xorriso/opts_p_z.c index 06312618..2369f807 100644 --- a/xorriso/opts_p_z.c +++ b/xorriso/opts_p_z.c @@ -1513,13 +1513,14 @@ int Xorriso_option_use_readline(struct XorrisO *xorriso, char *mode, int flag) /* Option -version */ int Xorriso_option_version(struct XorrisO *xorriso, int flag) { + sprintf(xorriso->result_line, "%sxorriso %d.%d.%d%s\n", #ifdef Xorriso_GNU_xorrisO - sprintf(xorriso->result_line, "GNU xorriso %s%s\n", - Xorriso_program_versioN, Xorriso_program_patch_leveL); + "GNU ", #else - sprintf(xorriso->result_line, "xorriso %s%s\n", - Xorriso_program_versioN, Xorriso_program_patch_leveL); + "", #endif /* ! Xorriso_GNU_xorrisO */ + Xorriso_header_version_majoR, Xorriso_header_version_minoR, + Xorriso_header_version_micrO, Xorriso_program_patch_leveL); Xorriso_result(xorriso, 0); sprintf(xorriso->result_line, "ISO 9660 Rock Ridge filesystem manipulator and CD/DVD/BD burn program\n"); @@ -1527,8 +1528,10 @@ int Xorriso_option_version(struct XorrisO *xorriso, int flag) "Copyright (C) 2010, Thomas Schmitt , libburnia project.\n"); Xorriso_result(xorriso, 0); sprintf(xorriso->result_line, - "xorriso version : %s%s\n", - Xorriso_program_versioN, Xorriso_program_patch_leveL); + "xorriso version : %d.%d.%d%s\n", + Xorriso_header_version_majoR, Xorriso_header_version_minoR, + Xorriso_header_version_micrO, Xorriso_program_patch_leveL); + Xorriso_result(xorriso, 0); sprintf(xorriso->result_line+strlen(xorriso->result_line), "Version timestamp : %s\n",Xorriso_timestamP); sprintf(xorriso->result_line+strlen(xorriso->result_line), diff --git a/xorriso/write_run.c b/xorriso/write_run.c index 57b2c46d..0eeacf1c 100644 --- a/xorriso/write_run.c +++ b/xorriso/write_run.c @@ -679,10 +679,10 @@ int Xorriso_write_session(struct XorrisO *xorriso, int flag) isoburn_igopt_set_scdbackup_tag(sopts, xorriso->scdbackup_tag_name, xorriso->scdbackup_tag_time, xorriso->scdbackup_tag_written); - if(image!=NULL && - strlen(Xorriso_program_versioN)+strlen(Xorriso_timestamP)<80) { - sprintf(xorriso_id, "XORRISO-%s %s", - Xorriso_program_versioN, Xorriso_timestamP); + if(image!=NULL && 12+strlen(Xorriso_timestamP)<80) { + sprintf(xorriso_id, "XORRISO-%d.%d.%d %s", + Xorriso_header_version_majoR, Xorriso_header_version_minoR, + Xorriso_header_version_micrO, Xorriso_timestamP); isoburn_version(&major, &minor, µ); if(strlen(xorriso_id)<80) sprintf(xorriso_id+strlen(xorriso_id), diff --git a/xorriso/xorriso.h b/xorriso/xorriso.h index 75d13952..8d16f76b 100644 --- a/xorriso/xorriso.h +++ b/xorriso/xorriso.h @@ -1,12 +1,29 @@ -/* Command line oriented batch and dialog tool which creates, loads, - manipulates and burns ISO 9660 filesystem images. +/* xorriso - libisoburn higher level API which creates, loads, manipulates + and burns ISO 9660 filesystem images. Copyright 2007-2010 Thomas Schmitt, Provided under GPL version 2 or later. - This file contains the public option interface of xorriso. + 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 "Options 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() + + 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 . */ #ifndef Xorriso_includeD @@ -16,9 +33,6 @@ struct XorrisO; -#define Xorriso_program_versioN "0.5.7" -#define Xorriso_program_patch_leveL "" - /* This may be changed to Xorriso_GNU_xorrisO in order to create GNU xorriso under GPLv3+ derived from above GPLv2+. @@ -29,13 +43,71 @@ struct XorrisO; /* --------------------- Fundamental Management ------------------- */ -/* Get the version text (e.g. "0.4.2") of the program code. - This may differ from Xorriso_program_versioN if xorriso is dynamically - linked to an application. - @param flag unused yet, submit 0 - @return readonly character string +/** 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 */ -char *Xorriso__get_version_text(int flag); +#define Xorriso_header_version_majoR 0 +#define Xorriso_header_version_minoR 5 +#define Xorriso_header_version_micrO 7 + + +/** Eventually 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 libray + 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. @@ -430,6 +502,7 @@ 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. diff --git a/xorriso/xorriso_main.c b/xorriso/xorriso_main.c index b2cf8e6f..9b1e6e83 100644 --- a/xorriso/xorriso_main.c +++ b/xorriso/xorriso_main.c @@ -1,11 +1,5 @@ -/* - - ( cd .. ; libisoburn-develop/xorriso/compile_xorriso.sh -g ) - -*/ - -/* Command line oriented batch and dialog tool which creates, loads, +/* xorriso - Command line oriented batch and dialog tool which creates, loads, manipulates and burns ISO 9660 filesystem images. Copyright 2007-2010 Thomas Schmitt, @@ -30,19 +24,27 @@ libisofs interprets and manipulates ISO 9660 directory trees. It generates the output stream which is handed over to libburn. - libisoburn encapsulates the connectivity issues between libburn and - libisofs. It also enables multi-session emulation on overwritable media - and random access file objects. - xorriso is intended as reference application of libisoburn. + libisoburn by its lower level API encapsulates the connectivity issues + between libburn and libisofs. This API also enables multi-session emulation + on overwritable media and random access file objects. - xorriso.h exposes the public functions of xorriso which are intended - to be used by programs which link with xorriso.o. These functions are - direct equivalents of the xorriso interpreter commands. - There is also the API for handling event messages. + xorriso is the higher level API of libisoburn which allows to operate all + three libraries by a unified set of commands. + xorriso.h exposes the public functions. + Among these functions are direct equivalents of the xorriso interpreter + commands. There are also functions for fundamental management and for + handling event messages. - The source is divided in two groups: + This file xorriso_main.c runs the xorriso API as batch and dialog program. + + One should not mix the use of the xorriso API with the use of the lower + level APIs of libburn, libisofs, libisoburn. + + + The xorriso source is divided in two groups: A set of source modules interacts with the libraries: + base_obj.[ch] fundamental operations of the XorrisO object lib_mgt.[ch] manages the relation between xorriso and the libraries drive_mgt.[ch] operates on drives and media @@ -56,6 +58,7 @@ xorrisoburn.h declarations needed by the non-library modules Another set is independent of the liburnia libraries: + parse_exec.c deals with parsing and interpretation of command input sfile.c functions around files and strings aux_objects.c various helper classes @@ -73,8 +76,6 @@ opts_i_o.c options -i* to -o* opts_p_z.c options -p* to -z* - xorriso_main.c the main program - xorriso_private.h contains the definition of struct Xorriso and for convenience includes the .h files of the non-library group. @@ -99,31 +100,99 @@ #include "xorriso.h" -#ifdef Xorriso_standalonE - -/* Make sure that both version tests always match. */ -#define Xorriso_main_program_versioN Xorriso_program_versioN - -#else /* Xorriso_standalonE */ - -/* xorriso consists only of a main() stub which has an own version to match - the version of libxorriso header and runtime code. +/* The minimum version of libisoburn to be used with this version of xorriso */ -#define Xorriso_main_program_versioN "0.5.7" - -#endif /* ! Xorriso_without_subS */ +#define Xorriso_req_majoR 0 +#define Xorriso_req_minoR 5 +#define Xorriso_req_micrO 7 static void yell_xorriso() { fprintf(stderr, - "%sxorriso %s%s : RockRidge filesystem manipulator, libburnia project.\n\n", + "%sxorriso %d.%d.%d%s : RockRidge filesystem manipulator, libburnia project.\n\n", #ifdef Xorriso_GNU_xorrisO "GNU ", #else "", #endif - Xorriso_main_program_versioN, Xorriso_program_patch_leveL); + Xorriso_header_version_majoR, Xorriso_header_version_minoR, + Xorriso_header_version_micrO, Xorriso_program_patch_leveL); +} + + +/* Check whether build configuration and runtime linking are consistent. +*/ +static void check_compatibility() +{ + int lib_major, lib_minor, lib_micro; + +/* First an ugly compile time check for header version compatibility. + If everthing matches, then no C code is produced. In case of mismatch, + intentionally faulty C code will be inserted. +*/ +/* The minimum requirement of xorriso towards the libisoburn header + at compile time is defined above + Xorriso_req_majoR + Xorriso_req_minoR + Xorriso_req_micrO + It gets compared against the version macros in xorriso.h : + Xorriso_header_version_majoR + Xorriso_header_version_minoR + Xorriso_header_version_micrO + If the header is too old then the following code shall cause failure of + cdrskin compilation rather than to allow production of a program with + unpredictable bugs or memory corruption. + The compiler messages supposed to appear in this case are: + error: 'XORRISO_MISCONFIGURATION' undeclared (first use in this function) + error: 'INTENTIONAL_ABORT_OF_COMPILATION__HEADERFILE_xorriso_dot_h_TOO_OLD__SEE_xorriso_main_dot_c' undeclared (first use in this function) + error: 'XORRISO_MISCONFIGURATION_' undeclared (first use in this function) +*/ +/* The indendation is an advise of man gcc to help old compilers ignoring */ + #if Xorriso_req_majoR > Xorriso_header_version_majoR + #define Xorriso_dot_h_too_olD 1 + #endif + #if Xorriso_req_majoR == Xorriso_header_version_majoR && Xorriso_req_minoR > Xorriso_header_version_minoR + #define Xorriso_dot_h_too_olD 1 + #endif + #if Xorriso_req_minoR == Xorriso_header_version_minoR && Xorriso_req_micrO > Xorriso_header_version_micrO + #define Xorriso_dot_h_too_olD 1 + #endif + +#ifdef Xorriso_dot_h_too_olD +XORRISO_MISCONFIGURATION = 0; +INTENTIONAL_ABORT_OF_COMPILATION__HEADERFILE_xorriso_dot_h_TOO_OLD__SEE_xorriso_main_dot_c = 0; +XORRISO_MISCONFIGURATION_ = 0; +#endif + +/* End of ugly compile time test (scroll up for explanation) */ + + + /* Needed are at least 44 bits in signed type off_t . + This is a popular mistake in configuration or compilation. + */ + if(sizeof(off_t) < 6) { + yell_xorriso(); + fprintf(stderr, + "xorriso : FATAL : Compile time misconfiguration. sizeof(off_t) too small.\n\n"); + exit(4); + } + + /* Check whether the linked xorriso code is young enough. + */ + if(! Xorriso__is_compatible(Xorriso_header_version_majoR, + Xorriso_header_version_minoR, + Xorriso_header_version_micrO, 0)) { + yell_xorriso(); + Xorriso__version(&lib_major, &lib_minor, &lib_micro); + fprintf(stderr, + "xorriso : FATAL : libisoburn/xorriso runtime version mismatch. Found %d.%d.%d, need %d.%d.%d\n\n", + lib_major, lib_minor, lib_micro, + Xorriso_header_version_majoR, Xorriso_header_version_minoR, + Xorriso_header_version_micrO); + exit(4); + } + } @@ -133,26 +202,7 @@ int main(int argc, char **argv) struct XorrisO *xorriso= NULL; char **orig_argv= NULL; - if(sizeof(off_t) < 8) { - yell_xorriso(); - fprintf(stderr, - "xorriso : FATAL : Compile time misconfiguration. sizeof(off_t) too small.\n\n"); - exit(4); - } - if(strcmp(Xorriso_main_program_versioN, Xorriso_program_versioN)) { - yell_xorriso(); - fprintf(stderr, - "xorriso : FATAL : libxorriso compile time version mismatch. Found %s\n\n", - Xorriso_program_versioN); - exit(4); - } - if(strcmp(Xorriso_program_versioN, Xorriso__get_version_text(0))) { - yell_xorriso(); - fprintf(stderr, - "xorriso : FATAL : libxorriso runtime version mismatch. Found %s\n\n", - Xorriso__get_version_text(0)); - exit(4); - } + check_compatibility(); /* might exit() */ if(argc < 2) { yell_xorriso(); @@ -178,7 +228,9 @@ int main(int argc, char **argv) yell_xorriso(); - /* The following functions are allowed only after this initialization */ + /* The following command interpreters are allowed only after this + initialization. + */ ret= Xorriso_startup_libraries(xorriso, 0); if(ret <= 0) {ret= 4; goto emergency_exit;} diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index dbb8b04c..10136b2b 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2010.05.21.132937" +#define Xorriso_timestamP "2010.05.21.133627"