Passenger: Utils.h Source File

- Main Page
- Modules
- Namespaces
- Classes
- Files

- File List

# Utils.h

    00001 /*
    00002  *  Phusion Passenger - http://www.modrails.com/
    00003  *  Copyright (c) 2010 Phusion
    00004  *
    00005  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
    00006  *
    00007  *  Permission is hereby granted, free of charge, to any person obtaining a copy
    00008  *  of this software and associated documentation files (the "Software"), to deal
    00009  *  in the Software without restriction, including without limitation the rights
    00010  *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    00011  *  copies of the Software, and to permit persons to whom the Software is
    00012  *  furnished to do so, subject to the following conditions:
    00013  *
    00014  *  The above copyright notice and this permission notice shall be included in
    00015  *  all copies or substantial portions of the Software.
    00016  *
    00017  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    00018  *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    00019  *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    00020  *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    00021  *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    00022  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    00023  *  THE SOFTWARE.
    00024  */
    00025 #ifndef _PASSENGER_UTILS_H_
    00026 #define _PASSENGER_UTILS_H_
    00027
    00028 #include <boost/shared_ptr.hpp>
    00029 #include <boost/function.hpp>
    00030 #include <sys/types.h>
    00031 #include <sys/stat.h>
    00032 #include <string>
    00033 #include <vector>
    00034 #include <utility>
    00035 #include <sstream>
    00036 #include <cstdio>
    00037 #include <climits>
    00038 #include <cstdlib>
    00039 #include <cstring>
    00040 #include <errno.h>
    00041 #include <unistd.h>
    00042 #include "StaticString.h"
    00043 #include "Exceptions.h"
    00044
    00045 namespace Passenger {
    00046
    00047 using namespace std;
    00048 using namespace boost;
    00049
    00050 static const uid_t USER_NOT_GIVEN = (uid_t) -1;
    00051 static const gid_t GROUP_NOT_GIVEN = (gid_t) -1;
    00052
    00053 typedef struct CachedFileStat CachedFileStat;
    00054 class ResourceLocator;
    00055
    00056 /** Enumeration which indicates what kind of file a file is. */
    00057 typedef enum {
    00058         /** The file doesn't exist. */
    00059         FT_NONEXISTANT,
    00060         /** A regular file or a symlink to a regular file. */
    00061         FT_REGULAR,
    00062         /** A directory. */
    00063         FT_DIRECTORY,
    00064         /** Something else, e.g. a pipe or a socket. */
    00065         FT_OTHER
    00066 } FileType;
    00067
    00068 /**
    00069  * Convenience shortcut for creating a <tt>shared_ptr</tt>.
    00070  * Instead of:
    00071  * @code
    00072  *    shared_ptr<Foo> foo;
    00073  *    ...
    00074  *    foo = shared_ptr<Foo>(new Foo());
    00075  * @endcode
    00076  * one can write:
    00077  * @code
    00078  *    shared_ptr<Foo> foo;
    00079  *    ...
    00080  *    foo = ptr(new Foo());
    00081  * @endcode
    00082  *
    00083  * @param pointer The item to put in the shared_ptr object.
    00084  * @ingroup Support
    00085  */
    00086 template<typename T> shared_ptr<T>
    00087 ptr(T *pointer) {
    00088         return shared_ptr<T>(pointer);
    00089 }
    00090
    00091 /**
    00092  * Check whether the specified file exists.
    00093  *
    00094  * @param filename The filename to check.
    00095  * @param cstat A CachedFileStat object, if you want to use cached statting.
    00096  * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL.
    00097  * @return Whether the file exists.
    00098  * @throws FileSystemException Unable to check because of a filesystem error.
    00099  * @throws TimeRetrievalException
    00100  * @throws boost::thread_interrupted
    00101  * @ingroup Support
    00102  */
    00103 bool fileExists(const StaticString &filename, CachedFileStat *cstat = 0,
    00104                 unsigned int throttleRate = 0);
    00105
    00106 /**
    00107  * Check whether 'filename' exists and what kind of file it is.
    00108  *
    00109  * @param filename The filename to check.
    00110  * @param mstat A CachedFileStat object, if you want to use cached statting.
    00111  * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL.
    00112  * @return The file type.
    00113  * @throws FileSystemException Unable to check because of a filesystem error.
    00114  * @throws TimeRetrievalException
    00115  * @throws boost::thread_interrupted
    00116  * @ingroup Support
    00117  */
    00118 FileType getFileType(const StaticString &filename, CachedFileStat *cstat = 0,
    00119                      unsigned int throttleRate = 0);
    00120
    00121 /**
    00122  * Create the given file with the given contents, permissions and ownership.
    00123  * This function does not leave behind junk files: if the ownership cannot be set
    00124  * or if not all data can be written then then the file will be deleted.
    00125  *
    00126  * @param filename The file to create.
    00127  * @param contents The contents to write to the file.
    00128  * @param permissions The desired file permissions.
    00129  * @param owner The desired file owner. Specify USER_NOT_GIVEN if you want to use the current
    00130  *              process's owner as the file owner.
    00131  * @param group The desired file group. Specify GROUP_NOT_GIVEN if you want to use the current
    00132  *              process's group as the file group.
    00133  * @param overwrite Whether to overwrite the file if it exists. If set to false
    00134  *                  and the file exists then nothing will happen.
    00135  * @throws FileSystemException Something went wrong.
    00136  * @ingroup Support
    00137  */
    00138 void createFile(const string &filename, const StaticString &contents,
    00139                 mode_t permissions = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH,
    00140                 uid_t owner = USER_NOT_GIVEN, gid_t group = GROUP_NOT_GIVEN,
    00141                 bool overwrite = true);
    00142
    00143 /**
    00144  * Returns a canonical version of the specified path. All symbolic links
    00145  * and relative path elements are resolved.
    00146  *
    00147  * @throws FileSystemException Something went wrong.
    00148  * @ingroup Support
    00149  */
    00150 string canonicalizePath(const string &path);
    00151
    00152 /**
    00153  * If <em>path</em> refers to a symlink, then this function resolves the
    00154  * symlink for 1 level. That is, if the symlink points to another symlink,
    00155  * then the other symlink will not be resolved. The resolved path is returned.
    00156  *
    00157  * If the symlink doesn't point to an absolute path, then this function will
    00158  * prepend <em>path</em>'s directory to the result.
    00159  *
    00160  * If <em>path</em> doesn't refer to a symlink then this method will return
    00161  * <em>path</em>.
    00162  *
    00163  * @throws FileSystemException Something went wrong.
    00164  * @ingroup Support
    00165  */
    00166 string resolveSymlink(const string &path);
    00167
    00168 /**
    00169  * Given a path, extracts its directory name.
    00170  *
    00171  * @ingroup Support
    00172  */
    00173 string extractDirName(const StaticString &path);
    00174
    00175 /**
    00176  * Given a path, extracts its base name.
    00177  *
    00178  * @ingroup Support
    00179  */
    00180 string extractBaseName(const StaticString &path);
    00181
    00182 /**
    00183  * Escape the given raw string into an XML value.
    00184  *
    00185  * @throws std::bad_alloc Something went wrong.
    00186  * @ingroup Support
    00187  */
    00188 string escapeForXml(const string &input);
    00189
    00190 /**
    00191  * Returns the username of the user that the current process is running as.
    00192  * If the user has no associated username, then "UID xxxx" is returned,
    00193  * where xxxx is the current UID.
    00194  */
    00195 string getProcessUsername();
    00196
    00197 /**
    00198  * Converts a mode string into a mode_t value.
    00199  *
    00200  * At this time only the symbolic mode strings are supported, e.g. something like looks
    00201  * this: "u=rwx,g=w,o=rx". The grammar is as follows:
    00202  * @code
    00203  *   mode   ::= (clause ("," clause)*)?
    00204  *   clause ::= who "=" permission*
    00205  *   who    ::= "u" | "g" | "o"
    00206  *   permission ::= "r" | "w" | "x" | "s"
    00207  * @endcode
    00208  *
    00209  * Notes:
    00210  * - The mode value starts with 0. So if you specify "u=rwx", then the group and world
    00211  *   permissions will be empty (set to 0).
    00212  * - The "s" permission is only allowed for who == "u" or who == "g".
    00213  * - The return value does not depend on the umask.
    00214  *
    00215  * @throws InvalidModeStringException The mode string cannot be parsed.
    00216  */
    00217 mode_t parseModeString(const StaticString &mode);
    00218
    00219 /**
    00220  * Return the path name for the directory in which the system stores general
    00221  * temporary files. This is usually "/tmp", but might be something else depending
    00222  * on some environment variables.
    00223  *
    00224  * @ensure result != NULL
    00225  * @ingroup Support
    00226  */
    00227 const char *getSystemTempDir();
    00228
    00229 /* Create a temporary directory for storing Phusion Passenger instance-specific
    00230  * temp files, such as temporarily buffered uploads, sockets for backend
    00231  * processes, etc.
    00232  * The directory that will be created is the one returned by
    00233  * <tt>getPassengerTempDir(false, parentDir)</tt>. This call stores the path to
    00234  * this temp directory in an internal variable, so that subsequent calls to
    00235  * getPassengerTempDir() will return the same path.
    00236  *
    00237  * The created temp directory will have several subdirectories:
    00238  * - webserver_private - for storing the web server's buffered uploads.
    00239  * - info - for storing files that allow external tools to query information
    00240  *          about a running Phusion Passenger instance.
    00241  * - backends - for storing Unix sockets created by backend processes.
    00242  * - master - for storing files such as the Passenger HelperServer socket.
    00243  *
    00244  * If a (sub)directory already exists, then it will not result in an error.
    00245  *
    00246  * The <em>userSwitching</em> and <em>lowestUser</em> arguments passed to
    00247  * this method are used for determining the optimal permissions for the
    00248  * (sub)directories. The permissions will be set as tightly as possible based
    00249  * on the values. The <em>workerUid</em> and <em>workerGid</em> arguments
    00250  * will be used for determining the owner of certain subdirectories.
    00251  *
    00252  * @note You should only call this method inside the web server's master
    00253  *       process. In case of Apache, this is the Apache control process,
    00254  *       the one that tends to run as root. This is because this function
    00255  *       will set directory permissions and owners/groups, which may require
    00256  *       root privileges.
    00257  *
    00258  * @param parentDir The directory under which the Phusion Passenger-specific
    00259  *                  temp directory should be created. This argument may be the
    00260  *                  empty string, in which case getSystemTempDir() will be used
    00261  *                  as the parent directory.
    00262  * @param userSwitching Whether user switching is turned on.
    00263  * @param lowestUser The user that the spawn manager and the pool server will
    00264  *                   run as, if user switching is turned off.
    00265  * @param workerUid The UID that the web server's worker processes are running
    00266  *                  as. On Apache, this is the UID that's associated with the
    00267  *                  'User' directive.
    00268  * @param workerGid The GID that the web server's worker processes are running
    00269  *                  as. On Apache, this is the GID that's associated with the
    00270  *                  'Group' directive.
    00271  * @throws IOException Something went wrong.
    00272  * @throws SystemException Something went wrong.
    00273  * @throws FileSystemException Something went wrong.
    00274  */
    00275 /* void createPassengerTempDir(const string &parentDir, bool userSwitching,
    00276                             const string &lowestUser,
    00277                             uid_t workerUid, gid_t workerGid); */
    00278
    00279 /**
    00280  * Create the directory at the given path, creating intermediate directories
    00281  * if necessary. The created directories' permissions are exactly as specified
    00282  * by the 'mode' parameter (i.e. the umask will be ignored). You can specify
    00283  * this directory's owner and group through the 'owner' and 'group' parameters.
    00284  * A value of USER_NOT_GIVEN for 'owner' and/or GROUP_NOT_GIVEN 'group' means
    00285  * that the owner/group should not be changed.
    00286  *
    00287  * If 'path' already exists, then nothing will happen.
    00288  *
    00289  * @param mode A mode string, as supported by parseModeString().
    00290  * @throws FileSystemException Something went wrong.
    00291  * @throws InvalidModeStringException The mode string cannot be parsed.
    00292  */
    00293 void makeDirTree(const string &path, const StaticString &mode = "u=rwx,g=,o=",
    00294         uid_t owner = USER_NOT_GIVEN, gid_t group = GROUP_NOT_GIVEN);
    00295
    00296 /**
    00297  * Remove an entire directory tree recursively. If the directory doesn't exist then this
    00298  * function does nothing.
    00299  *
    00300  * @throws FileSystemException Something went wrong.
    00301  */
    00302 void removeDirTree(const string &path);
    00303
    00304 /**
    00305  * Check whether the specified directory is a valid Ruby on Rails
    00306  * application root directory.
    00307  *
    00308  * @param cstat A CachedFileStat object, if you want to use cached statting.
    00309  * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL.
    00310  * @throws FileSystemException Unable to check because of a system error.
    00311  * @throws TimeRetrievalException
    00312  * @throws boost::thread_interrupted
    00313  * @ingroup Support
    00314  */
    00315 bool verifyRailsDir(const string &dir, CachedFileStat *cstat = 0,
    00316                     unsigned int throttleRate = 0);
    00317
    00318 /**
    00319  * Check whether the specified directory is a valid Rack application
    00320  * root directory.
    00321  *
    00322  * @param cstat A CachedFileStat object, if you want to use cached statting.
    00323  * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL.
    00324  * @throws FileSystemException Unable to check because of a filesystem error.
    00325  * @throws TimeRetrievalException
    00326  * @throws boost::thread_interrupted
    00327  * @ingroup Support
    00328  */
    00329 bool verifyRackDir(const string &dir, CachedFileStat *cstat = 0,
    00330                    unsigned int throttleRate = 0);
    00331
    00332 /**
    00333  * Check whether the specified directory is a valid WSGI application
    00334  * root directory.
    00335  *
    00336  * @param cstat A CachedFileStat object, if you want to use cached statting.
    00337  * @param throttleRate A throttle rate for cstat. Only applicable if cstat is not NULL.
    00338  * @throws FileSystemException Unable to check because of a filesystem error.
    00339  * @throws TimeRetrievalException
    00340  * @throws boost::thread_interrupted
    00341  * @ingroup Support
    00342  */
    00343 bool verifyWSGIDir(const string &dir, CachedFileStat *cstat = 0,
    00344                    unsigned int throttleRate = 0);
    00345
    00346 void prestartWebApps(const ResourceLocator &locator, const string &serializedprestartURLs);
    00347
    00348 /**
    00349  * Runs the given function and catches any tracable_exceptions. Upon catching such an exception,
    00350  * its message and backtrace will be printed. If toAbort is true then it will call abort(),
    00351  * otherwise the exception is swallowed.
    00352  * thread_interrupted and all other exceptions are silently propagated.
    00353  */
    00354 void runAndPrintExceptions(const function<void ()> &func, bool toAbort);
    00355 void runAndPrintExceptions(const function<void ()> &func);
    00356
    00357 /**
    00358  * Returns the system's host name.
    00359  *
    00360  * @throws SystemException The host name cannot be retrieved.
    00361  */
    00362 string getHostName();
    00363
    00364 /**
    00365  * Convert a signal number to its associated name.
    00366  */
    00367 string getSignalName(int sig);
    00368
    00369 /**
    00370  * Resets the current process's signal handler disposition and signal mask
    00371  * to default values. One should call this every time one forks a child process;
    00372  * non-default signal masks/handler dispositions can cause all kinds of weird quirks,
    00373  * like waitpid() malfunctioning on OS X.
    00374  *
    00375  * This function is async-signal safe.
    00376  */
    00377 void resetSignalHandlersAndMask();
    00378
    00379 /**
    00380  * Close all file descriptors that are higher than <em>lastToKeepOpen</em>.
    00381  * This function is async-signal safe. But make sure there are no other
    00382  * threads running that might open file descriptors!
    00383  */
    00384 void closeAllFileDescriptors(int lastToKeepOpen);
    00385
    00386
    00387 /**
    00388  * Represents a buffered upload file.
    00389  *
    00390  * @ingroup Support
    00391  */
    00392 class BufferedUpload {
    00393 public:
    00394         /** The file handle. */
    00395         FILE *handle;
    00396
    00397         /**
    00398          * Create an empty upload bufer file, and open it for reading and writing.
    00399          *
    00400          * @throws SystemException Something went wrong.
    00401          */
    00402         BufferedUpload(const string &dir, const char *identifier = "temp") {
    00403                 char templ[PATH_MAX];
    00404                 int fd;
    00405
    00406                 snprintf(templ, sizeof(templ), "%s/%s.XXXXXX", dir.c_str(), identifier);
    00407                 templ[sizeof(templ) - 1] = '\0';
    00408                 fd = mkstemp(templ);
    00409                 if (fd == -1) {
    00410                         char message[1024];
    00411                         int e = errno;
    00412
    00413                         snprintf(message, sizeof(message), "Cannot create a temporary file '%s'", templ);
    00414                         message[sizeof(message) - 1] = '\0';
    00415                         throw SystemException(message, e);
    00416                 }
    00417
    00418                 /* We use a POSIX trick here: the file's permissions are set to "u=,g=,o="
    00419                  * and the file is deleted immediately from the filesystem, while we
    00420                  * keep its file handle open. The result is that no other processes
    00421                  * will be able to access this file's contents anymore, except us.
    00422                  * We now have an anonymous disk-backed buffer.
    00423                  */
    00424                 fchmod(fd, 0000);
    00425                 unlink(templ);
    00426
    00427                 handle = fdopen(fd, "w+");
    00428         }
    00429
    00430         ~BufferedUpload() {
    00431                 fclose(handle);
    00432         }
    00433 };
    00434
    00435 } // namespace Passenger
    00436
    00437 #endif /* _PASSENGER_UTILS_H_ */
    00438