Adapted version checking to new library situation

libisoburn/trunk/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))));
 }
 
 

libisoburn/trunk/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",
+         "GNU ",
-         Xorriso_program_versioN, Xorriso_program_patch_leveL);
 #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 <scdbackup@gmx.net>, libburnia project.\n");
  Xorriso_result(xorriso, 0);
  sprintf(xorriso->result_line,
-         "xorriso version   :  %s%s\n",
+         "xorriso version   :  %d.%d.%d%s\n",
-         Xorriso_program_versioN, Xorriso_program_patch_leveL);
+         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),

libisoburn/trunk/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 &&
+ if(image!=NULL && 12+strlen(Xorriso_timestamP)<80) {
-    strlen(Xorriso_program_versioN)+strlen(Xorriso_timestamP)<80) {
+   sprintf(xorriso_id, "XORRISO-%d.%d.%d %s",
-   sprintf(xorriso_id, "XORRISO-%s %s",
+           Xorriso_header_version_majoR, Xorriso_header_version_minoR,
-           Xorriso_program_versioN, Xorriso_timestamP);
+           Xorriso_header_version_micrO, Xorriso_timestamP);
    isoburn_version(&major, &minor, &micro);
    if(strlen(xorriso_id)<80)
      sprintf(xorriso_id+strlen(xorriso_id),

libisoburn/trunk/xorriso/xorriso.h

@@ -1,12 +1,29 @@
 
-/* Command line oriented batch and dialog tool which creates, loads,
+/* xorriso - libisoburn higher level API which creates, loads, manipulates
-   manipulates and burns ISO 9660 filesystem images.
+             and burns ISO 9660 filesystem images.
 
    Copyright 2007-2010 Thomas Schmitt, <scdbackup@gmx.net>
 
    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.
+/** These three release version numbers tell the revision of this header file
-   This may differ from Xorriso_program_versioN if xorriso is dynamically
+    and of the API which it describes. They shall be memorized by applications
-   linked to an application.
+    at build time.
-   @param flag     unused yet, submit 0
+    @since 0.5.8
-   @return         readonly character string
 */
-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.

libisoburn/trunk/xorriso/xorriso_main.c

@@ -1,11 +1,5 @@
 
-/*
+/* xorriso - Command line oriented batch and dialog tool which creates, loads,
-
-    ( cd .. ; libisoburn-develop/xorriso/compile_xorriso.sh -g )
-
-*/
-
-/* Command line oriented batch and dialog tool which creates, loads,
    manipulates and burns ISO 9660 filesystem images.
 
    Copyright 2007-2010 Thomas Schmitt, <scdbackup@gmx.net>
@@ -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
+   libisoburn by its lower level API encapsulates the connectivity issues
-   libisofs. It also enables multi-session emulation on overwritable media
+   between libburn and libisofs. This API also enables multi-session emulation
-   and random access file objects.
+   on overwritable media and random access file objects.
-   xorriso is intended as reference application of libisoburn.
 
-   xorriso.h exposes the public functions of xorriso which are intended
+   xorriso is the higher level API of libisoburn which allows to operate all
-   to be used by programs which link with xorriso.o. These functions are
+   three libraries by a unified set of commands. 
-   direct equivalents of the xorriso interpreter commands.
+   xorriso.h exposes the public functions.
-   There is also the API for handling event messages.
+   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
+/* The minimum version of libisoburn to be used with this version of xorriso
-
-/* 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.
 */
-#define Xorriso_main_program_versioN "0.5.7"
+#define Xorriso_req_majoR  0
-
+#define Xorriso_req_minoR  5
-#endif /* ! Xorriso_without_subS */
+#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) {
+ check_compatibility(); /* might exit() */
-   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);
- }
 
  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;}

libisoburn/trunk/xorriso/xorriso_timestamp.h

@@ -1 +1 @@
-#define Xorriso_timestamP "2010.05.21.132937"
+#define Xorriso_timestamP "2010.05.21.133627"