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   static const char *approot = NULL;
 141   return ((approot == NULL) && ((approot = getenv( "APPROOT" )) == NULL))
 142
 143     ? "c:/mingw/"       /* default, for failed environment look-up */
 144     : approot;          /* normal return value */
 145 }
 146
 147 #include "debug.h"
 148
 149 #if DEBUGLEVEL & DEBUG_INHIBIT_RITES_OF_PASSAGE
 150  /*
 151   * When debugging, (with rites of passage selected for debugging),
 152   * then we substitute debug message handlers for the real "rename()"
 153   * and "unlink()" functions used to implement the rites.
 154   */
 155 RITES_INLINE int mingw_get_rename( const char *from, const char *to )
 156 {
 157   /* Inline debugging message handler to report requests to perform
 158    * the file rename rite, with optional success/failure result.
 159    */
 160   fprintf( stderr, "rename: %s to %s\n", from, to );
 161   errno = (DEBUGLEVEL & DEBUG_FAIL_FILE_RENAME_RITE) ? EEXIST : EOK;
 162   return (DEBUGLEVEL & DEBUG_FAIL_FILE_RENAME_RITE) ? -1 : 0;
 163 }
 164
 165 RITES_INLINE int mingw_get_unlink( const char *name )
 166 {
 167   /* Inline debugging message handler to report requests to perform
 168    * the file "unlink" rite.
 169    */
 170   fprintf( stderr, "unlink: %s\n", name );
 171   return (DEBUGLEVEL & DEBUG_FAIL_FILE_UNLINK_RITE) ? -1 : 0;
 172 }
 173
 174 #else
 175  /* We are doing it for real...
 176   * Simply map the "rename" and "unlink" requests through to the
 177   * appropriate system calls.
 178   */
 179 # define mingw_get_rename( N1, N2 )     rename( (N1), (N2) )
 180 # define mingw_get_unlink( N1 )         unlink( (N1) )
 181 #endif
 182
 183 RITES_INLINE void mingw_get_remove( const char *name )
 184 {
 185   /* Inline helper to perform the "unlink" rite, provided a preceding
 186    * request, (presumably "rename"), has not failed with EEXIST status.
 187    */
 188   if( errno == EEXIST ) mingw_get_unlink( name );
 189 }
 190
 191 RITES_INLINE void perform_rites_of_passage( const wchar_t *name )
 192 {
 193   /* Local helper function, to perform the required rite of passage
 194    * for a single specified process image file, as specified by its
 195    * relative path name within the application directory tree.
 196    */
 197   const char *approot = approot_path();
 198
 199   /* We begin by allocating stack space for the absolute path names
 200    * for both the original file name and its backup name.
 201    */
 202   size_t buflen = snprintf( NULL, 0, "%s%S~", approot, name );
 203   char normal_name[ buflen ], backup_name[ 1 + buflen ];
 204
 205   /* Fill out this buffer pair with the requisite path names,
 206    * noting that the backup name is the same as the original
 207    * name, with a single tilde appended.
 208    */
 209   snprintf( normal_name, buflen, "%s%S", approot, name );
 210   snprintf( backup_name, ++buflen, "%s~", normal_name );
 211
 212   /* Clear any pre-existing error condition, then perform the
 213    * requisite "rename" and "unlink" rites, in the pre-scheduled
 214    * order appropriate to the build context.
 215    */
 216   errno = EOK;
 217   first_act( normal_name, backup_name );
 218   final_act( normal_name, backup_name );
 219 }
 220
 221 /* Here, we specify the variant portion of the implementation...
 222  */
 223 BEGIN_RITES_IMPLEMENTATION
 224 {
 225   /* ...where the requisite "rites of passage" are initiated
 226    * for each process image file affected, specifying each by
 227    * its path name relative to the root of the application's
 228    * installation directory tree.
 229    */
 230   perform_rites_of_passage( MINGW_GET_EXE );
 231   perform_rites_of_passage( MINGW_GET_DLL );
 232   END_RITES_IMPLEMENTATION
 233 }
 234
 235 #if IMPLEMENT_INITIATION_RITES == PHASE_ONE_RITES
 236 /*
 237  * The following inline functions are required, specifically
 238  * and exclusively, for the first phase of initiation rites...
 239  */
 240 # include <process.h>
 241 # include <sys/types.h>
 242 # include <sys/stat.h>
 243 # include <fcntl.h>
 244
 245 RITES_INLINE const char *lockfile_name( void )
 246 {
 247   /* Helper to identify the absolute path for the lock file...
 248    */
 249   static char *lockfile = NULL;
 250
 251   if( lockfile == NULL )
 252   {
 253     /* We resolve this only once; this is the first reference,
 254      * (or all prior references were unsuccessfully resolved), so
 255      * we must resolve it now.
 256      */
 257     const char *lockpath = approot_path();
 258     const wchar_t *lockname = MINGW_GET_LCK;
 259     size_t wanted = 1 + snprintf( NULL, 0, "%s%S", lockpath, lockname );
 260     if( (lockfile = malloc( wanted )) != NULL )
 261       snprintf( lockfile, wanted, "%s%S", lockpath, lockname );
 262   }
 263   /* In any case, we return the pointer as resolved on first call.
 264    */
 265   return lockfile;
 266 }
 267
 268 /* Provide a facility for clearing a stale lock; for Win32, we may
 269  * simply refer this to the "unlink()" function, because the system
 270  * will not permit us to unlink a lock file which is owned by any
 271  * active process; (i.e. it is NOT a stale lock).
 272  *
 273  * FIXME: This will NOT work on Linux (or other Unixes), where it
 274  *        IS permitted to unlink an active lock file; to support
 275  *        such systems, we will need to provide a more robust
 276  *        implementation for "unlink_if_stale()".
 277  */
 278 #define unlink_if_stale  mingw_get_unlink
 279
 280 RITES_INLINE int pkgInitRites( const char *progname )
 281 {
 282   /* Helper to acquire an exclusive execution lock, and if sucessful,
 283    * to establish pre-conditions to permit self-upgrade.
 284    */
 285   int lock;
 286   const char *lockfile;
 287
 288   /* First, attempt to clear any prior (stale) lock, then create
 289    * a new one.  (Note that we DON'T use O_TEMPORARY here; on Win2K,
 290    * it leads to strange behaviour when another process attempts to
 291    * unlink a stale lock file).
 292    */
 293   unlink_if_stale( lockfile = lockfile_name() );
 294   if( (lock = open( lockfile, O_RDWR | O_CREAT | O_EXCL, S_IWRITE )) < 0 )
 295   {
 296     /* We failed to acquire the lock; diagnose failure...
 297      */
 298     fprintf( stderr, "%s: cannot acquire lock for exclusive execution\n",
 299         progname
 300       );
 301     fprintf( stderr, "%s: ", progname ); perror( lockfile );
 302     if( errno == EEXIST )
 303       fprintf( stderr, "%s: another mingw-get process appears to be running\n",
 304           progname
 305         );
 306   }
 307
 308   /* Return the lock, indicating success or failure as appropriate.
 309    */
 310   return lock;
 311 }
 312
 313 RITES_INLINE int pkgLastRites( int lock, const char *progname )
 314 {
 315   /* Inline helper to clear the lock acquired by "pkgInitRites()",
 316    * and to initiate clean-up of the changes made by "invoke_rites()"
 317    * when it is invoked in second phase of initiation rites.
 318    */
 319   const char *approot = approot_path();
 320   const char *lastrites = "libexec/mingw-get/lastrites.exe";
 321   char rites[1 + snprintf( NULL, 0, "%s%s", approot, lastrites )];
 322
 323   /* Clear the lock; note that we must both close AND unlink the
 324    * lock file, because we didn't open it as O_TEMPORARY.
 325    */
 326   close( lock );
 327   unlink( lockfile_name() );
 328
 329   /* Initiate clean-up; we hand this off to a free-standing process,
 330    * so that it may delete the old EXE and DLL image files belonging to
 331    * this process, if they were upgraded since acquiring the lock.
 332    *
 333    * Note that we use the execl() function to invoke the clean-up
 334    * process.  However, we recognise that Microsoft's implementation
 335    * of this function does NOT behave in a POSIXly correct manner;
 336    * specifically, it returns control immediately to the calling
 337    * process, causing it to resume execution concurrently with the
 338    * exec()ed process, whereas POSIXly correct behaviour would cause
 339    * the calling process to wait for the exec()ed process.  This
 340    * lack of POSIX-like behaviour is unfortunate, since it results
 341    * in a potential race condition between the exec()ed process and
 342    * the calling process, should the latter immediately attempt to
 343    * invoke a new instance of mingw-get.  To mitigate this potential
 344    * race condition, we call the "invoke_rites()" function to pre-empt
 345    * as much as possible of the processing to be performed by the
 346    * clean-up program, recognising that we can be only partially
 347    * successful, (but silently ignoring the partial failure), before
 348    * calling execl() to complete those clean-up aspects which cannot
 349    * be successfully performed in this pre-emptive fashion.
 350    */
 351   snprintf( rites, sizeof( rites ), "%s%s", approot, lastrites );
 352   invoke_rites(); execl( rites, "lastrites", NULL );
 353
 354   /* We should never get to here; if we do...
 355    * Diagnose a problem, and bail out.
 356    */
 357   fprintf( stderr, "%s: execl: ", progname ); perror( lastrites );
 358   return EXIT_FATAL;
 359 }
 360
 361 #endif
 362
 363 #endif /* BEGIN_RITES_IMPLEMENTATION: $RCSfile$: end of file */