include/ignorecase.h

   1 #ifndef INCL_PHYSFSEXT_IGNORECASE_H
   2 #define INCL_PHYSFSEXT_IGNORECASE_H
   3
   4 /** \file ignorecase.h */
   5
   6 /**
   7  * \mainpage PhysicsFS ignorecase
   8  *
   9  * This is an extension to PhysicsFS to let you handle files in a
  10  *  case-insensitive manner, regardless of what sort of filesystem or
  11  *  archive they reside in. It does this by enumerating directories as
  12  *  needed and manually locating matching entries.
  13  *
  14  * Please note that this brings with it some caveats:
  15  *  - On filesystems that are case-insensitive to start with, such as those
  16  *    used on Windows or MacOS, you are adding extra overhead.
  17  *  - On filesystems that are case-sensitive, you might select the wrong dir
  18  *    or file (which brings security considerations and potential bugs). This
  19  *    code favours exact case matches, but you will lose access to otherwise
  20  *    duplicate filenames, or you might go down a wrong directory tree, etc.
  21  *    In practive, this is rarely a problem, but you need to be aware of it.
  22  *  - This doesn't do _anything_ with the write directory; you're on your
  23  *    own for opening the right files for writing. You can sort of get around
  24  *    this by adding your write directory to the search path, but then the
  25  *    interpolated directory tree can screw you up even more.
  26  *
  27  * This code should be considered an aid for legacy code. New development
  28  *  shouldn't do dumbass things that require this aid in the first place.  :)
  29  *
  30  * Usage: Set up PhysicsFS as you normally would, then use
  31  *  PHYSFSEXT_locateCorrectCase() to get a "correct" pathname to pass to
  32  *  functions like PHYSFS_openRead(), etc.
  33  *
  34  * License: this code is public domain. I make no warranty that it is useful,
  35  *  correct, harmless, or environmentally safe.
  36  *
  37  * This particular file may be used however you like, including copying it
  38  *  verbatim into a closed-source project, exploiting it commercially, and
  39  *  removing any trace of my name from the source (although I hope you won't
  40  *  do that). I welcome enhancements and corrections to this file, but I do
  41  *  not require you to send me patches if you make changes. This code has
  42  *  NO WARRANTY.
  43  *
  44  * Unless otherwise stated, the rest of PhysicsFS falls under the zlib license.
  45  *  Please see LICENSE.txt in the root of the source tree.
  46  *
  47  *  \author Ryan C. Gordon.
  48  */
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /**
  55  * \fn int PHYSFSEXT_locateCorrectCase(char *buf)
  56  * \brief Find an existing filename with matching case.
  57  *
  58  * This function will look for a path/filename that matches the passed in
  59  *  buffer. Each element of the buffer's path is checked for a
  60  *  case-insensitive match. The buffer must specify a null-terminated string
  61  *  in platform-independent notation.
  62  *
  63  * Please note results may be skewed differently depending on whether symlinks
  64  *  are enabled or not.
  65  *
  66  * Each element of the buffer is overwritten with the actual case of an
  67  *  existing match. If there is no match, the search aborts and reports an
  68  *  error. Exact matches are favored over case-insensitive matches.
  69  *
  70  * THIS IS RISKY. Please do not use this function for anything but crappy
  71  *  legacy code.
  72  *
  73  *   \param buf Buffer with null-terminated string of path/file to locate.
  74  *               This buffer will be modified by this function.
  75  *  \return zero if match was found, -1 if the final element (the file itself)
  76  *               is missing, -2 if one of the parent directories is missing.
  77  */
  78 int PHYSFSEXT_locateCorrectCase(char *buf);
  79
  80 #ifdef __cplusplus
  81 }
  82 #endif
  83
  84 #endif  /* include-once blocker. */
  85
  86 /* end of ignorecase.h ... */
  87