src/rites.c

   1 #ifndef BEGIN_RITES_IMPLEMENTATION
   2 /*
   3  * rites.c
   4  *
   5  * $Id$
   6  *
   7  * Written by Keith Marshall <keithmarshall@users.sourceforge.net>
   8  * Copyright (C) 2009, 2010, MinGW Project
   9  *
  10  *
  11  * Implementation of the main program function for the "lastrites.exe"
  12  * helper application; also, when included within another compilation
  13  * module, which pre-defines IMPLEMENT_INITIATION_RITES, it furnishes
  14  * the complementary "pkgInitRites()" and "pkgLastRites()" functions.
  15  *
  16  * The combination of a call to pkgInitRites() at program start-up,
  17  * followed by eventual termination by means of an "execl()" call to
  18  * invoke "lastrites.exe", equips "mingw-get" with the capability to
  19  * work around the MS-Windows limitation which prohibits replacement
  20  * of the image files for a running application, and so enables the
  21  * "mingw-get" application to upgrade itself.
  22  *
  23  *
  24  * This is free software.  Permission is granted to copy, modify and
  25  * redistribute this software, under the provisions of the GNU General
  26  * Public License, Version 3, (or, at your option, any later version),
  27  * as published by the Free Software Foundation; see the file COPYING
  28  * for licensing details.
  29  *
  30  * Note, in particular, that this software is provided "as is", in the
  31  * hope that it may prove useful, but WITHOUT WARRANTY OF ANY KIND; not
  32  * even an implied WARRANTY OF MERCHANTABILITY, nor of FITNESS FOR ANY
  33  * PARTICULAR PURPOSE.  Under no circumstances will the author, or the
  34  * MinGW Project, accept liability for any damages, however caused,
  35  * arising from the use of this software.
  36  *
  37  */
  38 #include <stdio.h>
  39 #include <stdlib.h>
  40 #include <errno.h>
  41
  42 #define MINGW_GET_EXE   L"bin/mingw-get.exe"
  43 #define MINGW_GET_LCK   L"var/lib/mingw-get/lock"
  44 #define MINGW_GET_DLL   L"libexec/mingw-get/mingw-get-0.dll"
  45 #define MINGW_GET_GUI   L"libexec/mingw-get/gui.exe"
  46
  47 /* We wish to define a number of helper functions, which we will prefer
  48  * to always compile to inline code; this convenience macro may be used
  49  * to facilitate achievement of this objective.
  50  */
  51 #define RITES_INLINE    static __inline__ __attribute__((__always_inline__))
  52
  53 #ifndef EOK
  54  /*
  55   * Typically, errno.h does not define a code for "no error", but
  56   * it's convenient for us to have one, so that we may clear "errno"
  57   * to ensure that we don't inadvertently react to a stale value.
  58   */
  59 # define EOK            0
  60 #endif
  61
  62 #ifdef IMPLEMENT_INITIATION_RITES
  63  /*
  64   * Normally specified by including this source file within another,
  65   * with an appropriate prior definition.  This indicates intent to
  66   * provide an inline implementation of either first or second phase
  67   * initiation rites, (mutually exclusively), depending on whether
  68   * IMPLEMENT_INITIATION_RITES is defined as PHASE_ONE_RITES, or as
  69   * PHASE_TWO_RITES; in either case, the associated code is invoked
  70   * via the locally implemented "invoke_rites()" function.
  71   */
  72 # define BEGIN_RITES_IMPLEMENTATION     RITES_INLINE void invoke_rites( void )
  73  /*
  74   * In this case, since the "invoke_rites()" function has nothing
  75   * to return, we declare a "do nothing" wrap-up hook.
  76   */
  77 # define END_RITES_IMPLEMENTATION
  78
  79 #else /* ! defined IMPLEMENT_INITIATION_RITES */
  80  /*
  81   * This alternative case is normally achieved by free-standing
  82   * compilation of rites.c; it implements the "main()" function
  83   * for the "lastrites.exe" helper program.
  84   */
  85 # define BEGIN_RITES_IMPLEMENTATION     int main()
  86  /*
  87   * In this case, we must return an exit code; we simply assume that,
  88   * for us. there is no meaningful concept of process failure, so we
  89   * always report success.
  90   */
  91 # define END_RITES_IMPLEMENTATION       return EXIT_SUCCESS;
  92 #endif
  93
  94 /* Provide selectors, to discriminate the two distinct classes
  95  * of initiation rites implementation, which may be specified as
  96  * the requisite form with IMPLEMENT_INITIATION_RITES.
  97  */
  98 #define PHASE_ONE_RITES  1
  99 #define PHASE_TWO_RITES  2
 100
 101 #if IMPLEMENT_INITIATION_RITES == PHASE_TWO_RITES
 102  /*
 103   * For the second phase initiation rites implementation, the
 104   * idea is to move the running executable and its associated DLL
 105   * out of the way, so that we may install upgraded versions while
 106   * the application is still running.  Thus, the first step is to
 107   * destroy any previously created backup copies of the running
 108   * program files which may still exist...
 109   */
 110 # define first_act( SOURCE, BACKUP )    mingw_get_unlink( (BACKUP) )
 111  /*
 112   * ...then, we schedule a potential pending removal of these, by
 113   * initially renaming them with their designated backup names...
 114   */
 115 # define final_act( SOURCE, BACKUP )    mingw_get_rename( (SOURCE), (BACKUP) )
 116
 117 #else /* ! PHASE_TWO_RITES */
 118  /*
 119   * In this case, we assume that the originally running process
 120   * may have invoked phase two initiation rites, so moving its own
 121   * executable and its associated DLL out of the way; we aim to move
 122   * them back again, by attempting to change the backup names back
 123   * to their original file names...
 124   */
 125 # define first_act( SOURCE, BACKUP )    mingw_get_rename( (BACKUP), (SOURCE) )
 126  /*
 127   * We expect the preceding "rename" to succeed; if it didn't, then
 128   * the most probable reason is that an upgrade has been installed,
 129   * in which case we may remove the obsolete backup versions.
 130   */
 131 # define final_act( SOURCE, BACKUP )    mingw_get_remove( (BACKUP) )
 132 #endif
 133
 134 RITES_INLINE const char *approot_path( void )
 135 {
 136   /* Inline helper to identify the root directory path for the running
 137    * application, (which "mingw-get" passes through the APPROOT variable
 138    * in the process environment)...
 139    *
 140    * Caution: although this is called more than once, DO NOT attempt to
 141    * optimise getenv() lookup by saving the returned pointer across calls;
 142    * the environment block may have been moved between calls, which makes
 143    * the pointer returned from a previous call potentially invalid!
 144    */
 145   char *approot;
 146   return ((approot = getenv( "APPROOT" )) == NULL)
 147
 148     ? "c:\\mingw\\"     /* default, for failed environment look-up */
 149     : approot;          /* normal return value */
 150 }
 151
 152 #include "debug.h"
 153
 154 #if DEBUGLEVEL & DEBUG_INHIBIT_RITES_OF_PASSAGE
 155  /*
 156   * When debugging, (with rites of passage selected for debugging),
 157   * then we substitute debug message handlers for the real "rename()"
 158   * and "unlink()" functions used to implement the rites.
 159   */
 160 RITES_INLINE int mingw_get_rename( const char *from, const char *to )
 161 {
 162   /* Inline debugging message handler to report requests to perform
 163    * the file rename rite, with optional success/failure result.
 164    */
 165   fprintf( stderr, "rename: %s to %s\n", from, to );
 166   errno = (DEBUGLEVEL & DEBUG_FAIL_FILE_RENAME_RITE) ? EEXIST : EOK;
 167   return (DEBUGLEVEL & DEBUG_FAIL_FILE_RENAME_RITE) ? -1 : 0;
 168 }
 169
 170 RITES_INLINE int mingw_get_unlink( const char *name )
 171 {
 172   /* Inline debugging message handler to report requests to perform
 173    * the file "unlink" rite.
 174    */
 175   fprintf( stderr, "unlink: %s\n", name );
 176   return (DEBUGLEVEL & DEBUG_FAIL_FILE_UNLINK_RITE) ? -1 : 0;
 177 }
 178
 179 #else
 180  /* We are doing it for real...
 181   * Simply map the "rename" and "unlink" requests through to the
 182   * appropriate system calls.
 183   */
 184 # define mingw_get_rename( N1, N2 )     rename( (N1), (N2) )
 185 # define mingw_get_unlink( N1 )         unlink( (N1) )
 186 #endif
 187
 188 RITES_INLINE void mingw_get_remove( const char *name )
 189 {
 190   /* Inline helper to perform the "unlink" rite, provided a preceding
 191    * request, (presumably "rename"), has not failed with EEXIST status.
 192    */
 193   if( errno == EEXIST ) mingw_get_unlink( name );
 194 }
 195
 196 RITES_INLINE void perform_rites_of_passage( const wchar_t *name )
 197 {
 198   /* Local helper function, to perform the required rite of passage
 199    * for a single specified process image file, as specified by its
 200    * relative path name within the application directory tree.
 201    */
 202   const char *approot = approot_path();
 203
 204   /* We begin by allocating stack space for the absolute path names
 205    * for both the original file name and its backup name.
 206    */
 207   size_t buflen = snprintf( NULL, 0, "%s%S~", approot, name );
 208   char normal_name[ buflen ], backup_name[ 1 + buflen ];
 209
 210   /* Fill out this buffer pair with the requisite path names,
 211    * noting that the backup name is the same as the original
 212    * name, with a single tilde appended.
 213    */
 214   snprintf( normal_name, buflen, "%s%S", approot, name );
 215   snprintf( backup_name, ++buflen, "%s~", normal_name );
 216
 217   /* Clear any pre-existing error condition, then perform the
 218    * requisite "rename" and "unlink" rites, in the pre-scheduled
 219    * order appropriate to the build context.
 220    */
 221   errno = EOK;
 222   first_act( normal_name, backup_name );
 223   final_act( normal_name, backup_name );
 224 }
 225
 226 /* Here, we specify the variant portion of the implementation...
 227  */
 228 BEGIN_RITES_IMPLEMENTATION
 229 {
 230   /* ...where the requisite "rites of passage" are initiated
 231    * for each process image file affected, specifying each by
 232    * its path name relative to the root of the application's
 233    * installation directory tree.
 234    */
 235   perform_rites_of_passage( MINGW_GET_EXE );
 236   perform_rites_of_passage( MINGW_GET_DLL );
 237   END_RITES_IMPLEMENTATION
 238 }
 239
 240 #if IMPLEMENT_INITIATION_RITES == PHASE_ONE_RITES
 241 /*
 242  * The following inline functions are required, specifically
 243  * and exclusively, for the first phase of initiation rites...
 244  */
 245 # include <process.h>
 246 # include <sys/types.h>
 247 # include <sys/stat.h>
 248 # include <fcntl.h>
 249
 250 RITES_INLINE const char *lockfile_name( void )
 251 {
 252   /* Helper to identify the absolute path for the lock file...
 253    */
 254   static char *lockfile = NULL;
 255
 256   if( lockfile == NULL )
 257   {
 258     /* We resolve this only once; this is the first reference,
 259      * (or all prior references were unsuccessfully resolved), so
 260      * we must resolve it now.
 261      */
 262     const char *lockpath = approot_path();
 263     const wchar_t *lockname = MINGW_GET_LCK;
 264     size_t wanted = 1 + snprintf( NULL, 0, "%s%S", lockpath, lockname );
 265     if( (lockfile = malloc( wanted )) != NULL )
 266       snprintf( lockfile, wanted, "%s%S", lockpath, lockname );
 267   }
 268   /* In any case, we return the pointer as resolved on first call.
 269    */
 270   return lockfile;
 271 }
 272
 273 /* Provide a facility for clearing a stale lock; for Win32, we may
 274  * simply refer this to the "unlink()" function, because the system
 275  * will not permit us to unlink a lock file which is owned by any
 276  * active process; (i.e. it is NOT a stale lock).
 277  *
 278  * FIXME: This will NOT work on Linux (or other Unixes), where it
 279  *        IS permitted to unlink an active lock file; to support
 280  *        such systems, we will need to provide a more robust
 281  *        implementation for "unlink_if_stale()".
 282  */
 283 #define unlink_if_stale  mingw_get_unlink
 284
 285 RITES_INLINE int pkgInitRites( const char *progname )
 286 {
 287   /* Helper to acquire an exclusive execution lock, and if sucessful,
 288    * to establish pre-conditions to permit self-upgrade.
 289    */
 290   int lock;
 291   const char *lockfile;
 292
 293   /* First, attempt to clear any prior (stale) lock, then create
 294    * a new one.  (Note that we DON'T use O_TEMPORARY here; on Win2K,
 295    * it leads to strange behaviour when another process attempts to
 296    * unlink a stale lock file).
 297    */
 298   unlink_if_stale( lockfile = lockfile_name() );
 299   if( (lock = open( lockfile, O_RDWR | O_CREAT | O_EXCL, S_IWRITE )) < 0 )
 300   {
 301     /* We failed to acquire the lock; diagnose failure...
 302      */
 303     fprintf( stderr, "%s: cannot acquire lock for exclusive execution\n",
 304         progname
 305       );
 306     fprintf( stderr, "%s: ", progname ); perror( lockfile );
 307     if( errno == EEXIST )
 308       fprintf( stderr, "%s: another mingw-get process appears to be running\n",
 309           progname
 310         );
 311   }
 312
 313   /* Return the lock, indicating success or failure as appropriate.
 314    */
 315   return lock;
 316 }
 317
 318 RITES_INLINE int pkgLastRites( int lock, const char *progname )
 319 {
 320   /* Inline helper to clear the lock acquired by "pkgInitRites()",
 321    * and to initiate clean-up of the changes made by "invoke_rites()"
 322    * when it is invoked in second phase of initiation rites.
 323    */
 324   const char *approot = approot_path();
 325   const char *lastrites = "libexec/mingw-get/lastrites.exe";
 326   char rites[1 + snprintf( NULL, 0, "%s%s", approot, lastrites )];
 327
 328   /* Clear the lock; note that we must both close AND unlink the
 329    * lock file, because we didn't open it as O_TEMPORARY.
 330    */
 331   close( lock );
 332   unlink( lockfile_name() );
 333
 334   /* Initiate clean-up; we hand this off to a free-standing process,
 335    * so that it may delete the old EXE and DLL image files belonging to
 336    * this process, if they were upgraded since acquiring the lock.
 337    *
 338    * Note that we use the execl() function to invoke the clean-up
 339    * process.  However, we recognise that Microsoft's implementation
 340    * of this function does NOT behave in a POSIXly correct manner;
 341    * specifically, it returns control immediately to the calling
 342    * process, causing it to resume execution concurrently with the
 343    * exec()ed process, whereas POSIXly correct behaviour would cause
 344    * the calling process to wait for the exec()ed process.  This
 345    * lack of POSIX-like behaviour is unfortunate, since it results
 346    * in a potential race condition between the exec()ed process and
 347    * the calling process, should the latter immediately attempt to
 348    * invoke a new instance of mingw-get.  To mitigate this potential
 349    * race condition, we call the "invoke_rites()" function to pre-empt
 350    * as much as possible of the processing to be performed by the
 351    * clean-up program, recognising that we can be only partially
 352    * successful, (but silently ignoring the partial failure), before
 353    * calling execl() to complete those clean-up aspects which cannot
 354    * be successfully performed in this pre-emptive fashion.
 355    */
 356   snprintf( rites, sizeof( rites ), "%s%s", approot, lastrites );
 357   invoke_rites(); execl( rites, "lastrites", NULL );
 358
 359   /* We should never get to here; if we do...
 360    * Diagnose a problem, and bail out.
 361    */
 362   fprintf( stderr, "%s: execl: ", progname ); perror( rites );
 363   return EXIT_FATAL;
 364 }
 365
 366 #endif
 367
 368 #endif /* BEGIN_RITES_IMPLEMENTATION: $RCSfile$: end of file */