1 #ifndef BEGIN_RITES_IMPLEMENTATION
7 * Written by Keith Marshall <keithmarshall@users.sourceforge.net>
8 * Copyright (C) 2009, 2010, MinGW Project
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.
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.
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.
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.
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"
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.
51 #define RITES_INLINE static __inline__ __attribute__((__always_inline__))
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.
62 #ifdef IMPLEMENT_INITIATION_RITES
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.
72 # define BEGIN_RITES_IMPLEMENTATION RITES_INLINE void invoke_rites( void )
74 * In this case, since the "invoke_rites()" function has nothing
75 * to return, we declare a "do nothing" wrap-up hook.
77 # define END_RITES_IMPLEMENTATION
79 #else /* ! defined IMPLEMENT_INITIATION_RITES */
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.
85 # define BEGIN_RITES_IMPLEMENTATION int main()
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.
91 # define END_RITES_IMPLEMENTATION return EXIT_SUCCESS;
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.
98 #define PHASE_ONE_RITES 1
99 #define PHASE_TWO_RITES 2
101 #if IMPLEMENT_INITIATION_RITES == PHASE_TWO_RITES
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...
110 # define first_act( SOURCE, BACKUP ) mingw_get_unlink( (BACKUP) )
112 * ...then, we schedule a potential pending removal of these, by
113 * initially renaming them with their designated backup names...
115 # define final_act( SOURCE, BACKUP ) mingw_get_rename( (SOURCE), (BACKUP) )
117 #else /* ! PHASE_TWO_RITES */
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...
125 # define first_act( SOURCE, BACKUP ) mingw_get_rename( (BACKUP), (SOURCE) )
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.
131 # define final_act( SOURCE, BACKUP ) mingw_get_remove( (BACKUP) )
134 RITES_INLINE const char *approot_path( void )
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)...
140 static const char *approot = NULL;
141 return ((approot == NULL) && ((approot = getenv( "APPROOT" )) == NULL))
143 ? "c:/mingw/" /* default, for failed environment look-up */
144 : approot; /* normal return value */
149 #if DEBUGLEVEL & DEBUG_INHIBIT_RITES_OF_PASSAGE
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.
155 RITES_INLINE int mingw_get_rename( const char *from, const char *to )
157 /* Inline debugging message handler to report requests to perform
158 * the file rename rite, with optional success/failure result.
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;
165 RITES_INLINE int mingw_get_unlink( const char *name )
167 /* Inline debugging message handler to report requests to perform
168 * the file "unlink" rite.
170 fprintf( stderr, "unlink: %s\n", name );
171 return (DEBUGLEVEL & DEBUG_FAIL_FILE_UNLINK_RITE) ? -1 : 0;
175 /* We are doing it for real...
176 * Simply map the "rename" and "unlink" requests through to the
177 * appropriate system calls.
179 # define mingw_get_rename( N1, N2 ) rename( (N1), (N2) )
180 # define mingw_get_unlink( N1 ) unlink( (N1) )
183 RITES_INLINE void mingw_get_remove( const char *name )
185 /* Inline helper to perform the "unlink" rite, provided a preceding
186 * request, (presumably "rename"), has not failed with EEXIST status.
188 if( errno == EEXIST ) mingw_get_unlink( name );
191 RITES_INLINE void perform_rites_of_passage( const wchar_t *name )
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.
197 const char *approot = approot_path();
199 /* We begin by allocating stack space for the absolute path names
200 * for both the original file name and its backup name.
202 size_t buflen = snprintf( NULL, 0, "%s%S~", approot, name );
203 char normal_name[ buflen ], backup_name[ 1 + buflen ];
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.
209 snprintf( normal_name, buflen, "%s%S", approot, name );
210 snprintf( backup_name, ++buflen, "%s~", normal_name );
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.
217 first_act( normal_name, backup_name );
218 final_act( normal_name, backup_name );
221 /* Here, we specify the variant portion of the implementation...
223 BEGIN_RITES_IMPLEMENTATION
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.
230 perform_rites_of_passage( MINGW_GET_EXE );
231 perform_rites_of_passage( MINGW_GET_DLL );
232 END_RITES_IMPLEMENTATION
235 #if IMPLEMENT_INITIATION_RITES == PHASE_ONE_RITES
237 * The following inline functions are required, specifically
238 * and exclusively, for the first phase of initiation rites...
240 # include <process.h>
241 # include <sys/types.h>
242 # include <sys/stat.h>
245 RITES_INLINE const char *lockfile_name( void )
247 /* Helper to identify the absolute path for the lock file...
249 static char *lockfile = NULL;
251 if( lockfile == NULL )
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.
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 );
263 /* In any case, we return the pointer as resolved on first call.
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).
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()".
278 #define unlink_if_stale mingw_get_unlink
280 RITES_INLINE int pkgInitRites( const char *progname )
282 /* Helper to acquire an exclusive execution lock, and if sucessful,
283 * to establish pre-conditions to permit self-upgrade.
286 const char *lockfile;
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).
293 unlink_if_stale( lockfile = lockfile_name() );
294 if( (lock = open( lockfile, O_RDWR | O_CREAT | O_EXCL, S_IWRITE )) < 0 )
296 /* We failed to acquire the lock; diagnose failure...
298 fprintf( stderr, "%s: cannot acquire lock for exclusive execution\n",
301 fprintf( stderr, "%s: ", progname ); perror( lockfile );
302 if( errno == EEXIST )
303 fprintf( stderr, "%s: another mingw-get process appears to be running\n",
308 /* Return the lock, indicating success or failure as appropriate.
313 RITES_INLINE int pkgLastRites( int lock, const char *progname )
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.
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 )];
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.
327 unlink( lockfile_name() );
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.
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.
351 snprintf( rites, sizeof( rites ), "%s%s", approot, lastrites );
352 invoke_rites(); execl( rites, "lastrites", NULL );
354 /* We should never get to here; if we do...
355 * Diagnose a problem, and bail out.
357 fprintf( stderr, "%s: execl: ", progname ); perror( lastrites );
363 #endif /* BEGIN_RITES_IMPLEMENTATION: $RCSfile$: end of file */