1 #ifndef INCL_PHYSFSEXT_IGNORECASE_H
2 #define INCL_PHYSFSEXT_IGNORECASE_H
4 /** \file ignorecase.h */
7 * \mainpage PhysicsFS ignorecase
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.
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.
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. :)
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.
34 * License: this code is public domain. I make no warranty that it is useful,
35 * correct, harmless, or environmentally safe.
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
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.
47 * \author Ryan C. Gordon.
55 * \fn int PHYSFSEXT_locateCorrectCase(char *buf)
56 * \brief Find an existing filename with matching case.
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.
63 * Please note results may be skewed differently depending on whether symlinks
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.
70 * THIS IS RISKY. Please do not use this function for anything but crappy
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.
78 int PHYSFSEXT_locateCorrectCase(char *buf);
84 #endif /* include-once blocker. */
86 /* end of ignorecase.h ... */