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