Changeset 25781 in project


Ignore:
Timestamp:
01/07/12 22:10:31 (9 years ago)
Author:
svnwiki
Message:

Anonymous wiki edit for IP [70.71.179.201]: Updated docs to 2.0

File:
1 edited

Legend:

Unmodified
Added
Removed

  • wiki/eggref/4/physfs

    r25461 r25781  
    11[[tags: egg physicsfs physfs zip 7z archive game]]
     2
     3== physicsfs
    24
    35PhysicsFS bindings for Chicken.
    … …  
    4143Remember that most archive types and platform filesystems store their filenames in a case-sensitive manner, so you should be careful to specify it correctly.
    4244
    43 Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir elements. Not only are these meaningless on MacOS Classic and/or Unix, they are a security hole. Also, symbolic links (which can be found in some archive types and directly in the filesystem on Unix platforms) are NOT followed until you call (permitSymbolicLinks #t). That's left to your own discretion, as following a symlink can allow for access outside the write dir and search paths. For portability, there is no mechanism for creating new symlinks in PhysicsFS.
     45Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir elements. Not only are these meaningless on MacOS Classic and/or Unix, they are a security hole. Also, symbolic links (which can be found in some archive types and directly in the filesystem on Unix platforms) are NOT followed until you call (permit-symbolic-links #t). That's left to your own discretion, as following a symlink can allow for access outside the write dir and search paths. For portability, there is no mechanism for creating new symlinks in PhysicsFS.
    4446
    4547The write dir is not included in the search path unless you specifically add it. While you CAN change the write dir as many times as you like, you should probably set it once and stick to it. Remember that your program will not have permission to write in every directory on Unix and NT systems.
    … …  
    4749All files are opened in binary mode; there is no endline conversion for textfiles. Other than that, PhysicsFS has some convenience functions for platform-independence. There is a function to tell you the current platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS), which is needed only to set up your search/write paths. There is a function to tell you what CD-ROM drives contain accessible discs, and a function to recommend a good search path, etc.
    4850
    49 A recommended order for the search path is the write dir, then the base dir, then the cdrom dir, then any archives discovered. Quake 3 does something like this, but moves the archives to the start of the search path. Build Engine games, like Duke Nukem 3D and Blood, place the archives last, and use the base dir for both searching and writing. There is a helper function (setSaneConfig) that puts together a basic configuration for you, based on a few parameters. Also see the comments on (getBaseDir), and (getUserDir) for info on what those are and how they can help you determine an optimal search path.
     51A recommended order for the search path is the write dir, then the base dir, then the cdrom dir, then any archives discovered. Quake 3 does something like this, but moves the archives to the start of the search path. Build Engine games, like Duke Nukem 3D and Blood, place the archives last, and use the base dir for both searching and writing. There is a helper function (set-sane-config) that puts together a basic configuration for you, based on a few parameters. Also see the comments on (get-base-dir), and (get-user-dir) for info on what those are and how they can help you determine an optimal search path.
    5052
    5153PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points in the search path. If a zipfile contains "maps/level.map" and you mount that archive at "mods/mymod", then you would have to open "mods/mymod/maps/level.map" to access the file, even though "mods/mymod" isn't actually specified in the .zip file. Unlike the Unix mentality of mounting a filesystem, "mods/mymod" doesn't actually have to exist when mounting the zipfile. It's a "virtual" directory. The mounting mechanism allows the developer to seperate archives in the tree and avoid trampling over files when added new archives, such as including mod support in a game...keeping external content on a tight leash in this manner can be of utmost importance to some applications.
    5254
    53 PhysicsFS is mostly thread safe. The error messages returned by (getLastError) are unique by thread, and library-state-setting functions are mutex'd. For efficiency, individual file accesses are not locked, so you can not safely read/write/seek/close/etc the same  file from two threads at the same time. Other race conditions are bugs  that should be reported/patched.
     55PhysicsFS is mostly thread safe. The error messages returned by (get-last-error) are unique by thread, and library-state-setting functions are mutex'd. For efficiency, individual file accesses are not locked, so you can not safely read/write/seek/close/etc the same  file from two threads at the same time. Other race conditions are bugs  that should be reported/patched.
    5456
    5557While you CAN use stdio/syscall file access in a program that has physfs calls, doing so is not recommended, and you can not use system filehandles with PhysicsFS and vice versa.
    … …  
    7173All strings passed through PhysicsFS are in null-terminated UTF-8 format. This means that if all you care about is English (ASCII characters <= 127) then you just use regular C strings. If you care about Unicode (and you should!) then you need to figure out what your platform wants, needs, and offers. If you are on Windows and build with Unicode support, your TCHAR strings are two bytes per character (this is called "UCS-2 encoding"). You should convert them to UTF-8 before handing them to PhysicsFS with (utf8FromUcs2). If you're using Unix or Mac OS X, your wchar_t strings are four bytes per character ("UCS-4 encoding"). Use (utf8FromUcs4). Mac OS X can give you UTF-8 directly from a CFString, and many Unixes generally give you C strings in UTF-8 format everywhere. If you have a single-byte high ASCII charset, like so-many European "codepages" you may be out of luck. We'll convert from "Latin1" to UTF-8 only, and never back to Latin1. If you're above ASCII 127, all bets are off: move to Unicode or use your platform's facilities. Passing a C string with high-ASCII data that isn't UTF-8 encoded will NOT do what you expect!
    7274
    73 Naturally, there's also (utf8ToUcs2) and (utf8ToUcs4) to get data back into a format you like. Behind the scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on Windows will be converted and used with the multibyte Windows APIs, for example.
     75Naturally, there's also (utf8-to-ucs2) and (utf8-to-ucs4) to get data back into a format you like. Behind the scenes, PhysicsFS will use Unicode where possible: the UTF-8 strings on Windows will be converted and used with the multibyte Windows APIs, for example.
    7476
    7577PhysicsFS offers basic encoding conversion support, but not a whole string library. Get your stuff into whatever format you can work with.
    … …  
    8183== Reference
    8284
    83 === File
    84 ; File : A PhysicsFS file handle.
     85=== Types
     86
     87==== <type>file</type>
     88
     89A PhysicsFS file handle.
    8590
    8691You get a pointer to one of these when you open a file for reading, writing, or appending via PhysicsFS.
    … …  
    8893As you can see from the lack of meaningful fields, you should treat this as opaque data. Don't try to manipulate the file handle, just pass the pointer you got, unmolested, to various PhysicsFS APIs.
    8994
    90 === ArchiveInfo
    91 
    92 ; ArchiveInfo : Information on various PhysicsFS-supported archives.
     95* <procedure>(file-opaque file)</procedure>
     96
     97Fetches the opaque pointer contained within the file struct.
     98
     99==== <type>archive-info</type>
     100
     101Information on various PhysicsFS-supported archives.
    93102
    94103This structure gives you details on what sort of archives are supported by this implementation of PhysicsFS. Archives tend to be things like ZIP files and such.
    95104
    96 Available fields:
    97 * extension : Archive file extension: "ZIP", for example.
    98 * description : Human-readable archive description.
    99 * author : Person who did support for this archive.
    100 * url : URL related to this archive
    101 
    102 ; Version : Information the version of PhysicsFS in use.
     105* <procedure>(make-archive-info)</procedure> : Constructs an archive-info record, not that you should ever need to.
     106* <procedure>(archive-info? archive-info)</procedure> : Tests if an object is an archive-info.
     107* <procedure>(archive-info-extension archive-info)</procedure> : Archive file extension: "ZIP", for example.
     108* <procedure>(archive-info-description archive-info)</procedure> : Human-readable archive description.
     109* <procedure>(archive-info-author archive-info)</procedure> : Person who did support for this archive.
     110* <procedure>(archive-info-url archive-info)</procedure> : URL related to this archive
     111
     112==== <type>version</type>
     113
     114Information the version of PhysicsFS in use.
    103115
    104116Represents the library's version as three levels: major revision (increments with massive changes, additions, and enhancements), minor revision (increments with backwards-compatible changes to the major revision), and patchlevel (increments with fixes to the minor revision).
    105117
    106 Available fields:
    107 * major : major revision
    108 * minor : minor revision
    109 * patch : patchlevel
     118* <procedure>(make-version)</procedure> : Constructs a version record, not that you should ever need to.
     119* <procedure>(version? version)</procedure> : Tests if an object is a version.
     120* <procedure>(version-major version)</procedure> : major revision
     121* <procedure>(version-minor version)</procedure> : minor revision
     122* <procedure>(version-patch version)</procedure> : patch level
    110123
    111124=== PhysicsFS state
    112125
    113 ; (getLinkedVersion) : Get the version of PhysicsFS that is linked against your program.
     126==== <procedure>(get-linked-version)</procedure>
     127
     128Get the version of PhysicsFS that is linked against your program.
    114129
    115130If you are using a shared library (DLL) version of PhysFS, then it is possible that it will be different than the version you compiled against.
    … …  
    117132This function may be called safely at any time, even before PHYSFS_init().
    118133
    119 ; (init) : Initialize the PhysicsFS library.
     134==== <procedure>(init)</procedure>
     135
     136 Initialize the PhysicsFS library.
    120137
    121138This must be called before any other PhysicsFS function.
    … …  
    125142Returns nonzero on success, zero on error. Specifics of the error can be gleaned from (getLastError).
    126143
    127 ; (deinit) : Deinitialize the PhysicsFS library.
     144==== <procedure>(deinit)</procedure>
     145
     146Deinitialize the PhysicsFS library.
    128147
    129148This closes any files opened via PhysicsFS, blanks the search/write paths, frees memory, and invalidates all of your file handles.
    … …  
    131150Note that this call can FAIL if there's a file open for writing that refuses to close (for example, the underlying operating system was buffering writes to network filesystem, and the fileserver has crashed, or a hard drive has failed, etc). It is usually best to close all write handles yourself before calling this function, so that you can gracefully handle a specific failure.
    132151
    133 Once successfully deinitialized, PHYSFS_init() can be called again to restart the subsystem. All default API states are restored at this point, with the exception of any custom allocator you might have specified, which survives between initializations.
     152Once successfully deinitialized, (init) can be called again to restart the subsystem. All default API states are restored at this point, with the exception of any custom allocator you might have specified, which survives between initializations.
    134153
    135154Returns nonzero on success, zero on error. Specifics of the error can be gleaned from (getLastError). If failure, state of PhysFS is undefined, and probably badly screwed up.
    136155
    137 ; (supportedArchiveTypes) : Get a list of supported archive types.
     156==== <procedure>(supported-archive-types)</procedure>
     157
     158Get a list of supported archive types.
    138159
    139160Get a list of archive types supported by this implementation of PhysicFS. These are the file formats usable for search path entries. This is for informational purposes only. Note that the extension listed is merely convention: if we list "ZIP", you can open a PkZip-compatible archive with an extension of "XYZ", if you like.
    … …  
    141162The returned value is a list of ArchiveInfo records.
    142163
    143 ; (getLastError) :  Get human-readable error information.
     164==== <procedure>(get-last-error)</procedure>
     165
     166Get human-readable error information.
    144167
    145168Get the last PhysicsFS error message as a human-readable string. This will be empty if there's been no error since the last call to this function. The pointer returned by this call points to an internal buffer. Each thread has a unique error state associated with it, but each time a new error message is set, it will overwrite the previous one associated with that thread. It is safe to call this function at anytime, even before (init).
    … …  
    147170It is not wise to expect a specific string of characters here, since the error message may be localized into an unfamiliar language. These strings are meant to be passed on directly to the user.
    148171
    149 ; (getDirSeparator) : Get platform-dependent dir separator string.
     172==== <procedure>(get-dir-separator)</procedure>
     173
     174Get platform-dependent dir separator string.
    150175
    151176This returns "\\" on win32, "/" on Unix, and ":" on MacOS. It may be more than one character, depending on the platform, and your code should take that into account. Note that this is only useful for setting up the search/write paths, since access into those dirs always use '/' (platform-independent notation) to separate directories. This is also handy for getting platform-independent access when using stdio calls.
    152177
    153 ; (permitSymbolicLinks bool) : Enable or disable following of symbolic links.
     178==== <procedure>(permit-symbolic-links bool)</procedure>
     179
     180Enable or disable following of symbolic links.
    154181
    155182Some physical filesystems and archives contain files that are just pointers to other files. On the physical filesystem, opening such a link will (transparently) open the file that is pointed to.
    … …  
    163190Symbolic link permission can be enabled or disabled at any time after you've called (init), and is disabled by default.
    164191
    165 ; (getCdRomDirs) : Get an array of paths to available CD-ROM drives.
     192==== <procedure>(get-cdrom-dirs)</procedure>
     193
     194Get an array of paths to available CD-ROM drives.
    166195
    167196The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or whatnot on Unix). Dirs are only returned if there is a disc ready and accessible in the drive. So if you've got two drives (D: and E:), and only E: has a disc in it, then that's all you get. If the user inserts a disc in D: and you call this function again, you get both drives. If, on a Unix box, the user unmounts a disc and remounts it elsewhere, the next call to this function will reflect that change.
    … …  
    171200This call may block while drives spin up. Be forewarned.
    172201
    173 ; (getBaseDir) : Get the path where the application resides.
     202==== <procedure>(get-base-dir)</procedure>
     203
     204Get the path where the application resides.
    174205
    175206Helper function.
    … …  
    179210You should probably use the base dir in your search path.
    180211
    181 ; (getUserDir) : Get the path where user's home directory resides.
     212==== <procedure>(get-user-dir)</procedure>
     213
     214Get the path where user's home directory resides.
    182215
    183216Helper function.
    … …  
    187220You should probably use the user dir as the basis for your write dir, and also put it near the beginning of your search path.
    188221
    189 ; (getWriteDir) : Get path where PhysicsFS will allow file writing.
     222==== <procedure>(get-write-dir)</procedure>
     223
     224Get path where PhysicsFS will allow file writing.
    190225
    191226Get the current write dir. The default write dir is NULL.
    192227
    193 ; (setWriteDir dir) : Tell PhysicsFS where it may write files.
     228==== <procedure>(set-write-dir dir)</procedure>
     229
     230Tell PhysicsFS where it may write files.
    194231
    195232Set a new write dir. This will override the previous setting.
    … …  
    197234This call will fail (and fail to change the write dir) if the current write dir still has files open in it.
    198235
    199 ; (addToSearchPath newDir appendToPath)
     236==== <procedure>(add-to-search-path newDir appendToPath)</procedure>
    200237
    201238Add an archive or directory to the search path.
    … …  
    205242You must use this and not (mount) if binary compatibility with PhysicsFS 1.0 is important (which it may not be for many people).
    206243
    207 ; (removeFromSearchPath oldDir) : Remove a directory or archive from the search path.
     244==== <procedure>(remove-from-search-path oldDir)</procedure>
     245
     246Remove a directory or archive from the search path.
    208247
    209248This must be a (case-sensitive) match to a dir or archive already in the search path, specified in platform-dependent notation.
    … …  
    211250This call will fail (and fail to remove from the path) if the element still has files open in it.
    212251
    213 ; (getSearchPath) : Get the current search path.
     252==== <procedure>(get-search-path)</procedure>
     253
     254Get the current search path.
    214255
    215256The default search path is an empty list.
    216257
    217 ; (setSaneConfig organization appName archiveExt includeCdRoms archivesFirst) : Set up sane, default paths.
     258==== <procedure>(set-sane-config organization appName archiveExt includeCdRoms archivesFirst)</procedure>
     259
     260Set up sane, default paths.
    218261
    219262Helper function.
    … …  
    226269
    227270* The Write Dir (created if it doesn't exist)
    228 * The Base Dir (getBaseDir)
     271* The Base Dir (get-base-dir)
    229272* All found CD-ROM dirs (optionally)
    230273
    … …  
    234277=== Directory Management
    235278
    236 ; (mkdir dirName) : Create a directory.
     279==== <procedure>(mkdir dirName)</procedure>
     280
     281Create a directory.
    237282
    238283This is specified in platform-independent notation in relation to the write dir. All missing parent directories are also created if they don't exist.
    … …  
    240285So if you've got the write dir set to "C:\mygame\writedir" and call (mkdir "downloads/maps") then the directories "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps" will be created if possible. If the creation of "maps" fails after we have successfully created "downloads", then the function leaves the created directory behind and reports failure.
    241286
    242 ; (delete filename) : Delete a file or directory.
     287==== <procedure>(delete filename)</procedure>
     288
     289Delete a file or directory.
    243290
    244291(filename) is specified in platform-independent notation in relation to the write dir.
    … …  
    254301Chances are, the bits that make up the file still exist, they are just made available to be written over at a later point. Don't consider this a security method or anything.  :)
    255302
    256 ; (getRealDir filename) : Figure out where in the search path a file resides.
     303==== <procedure>(get-real-dir filename)</procedure>
     304
     305Figure out where in the search path a file resides.
    257306
    258307The file is specified in platform-independent notation. The returned filename will be the element of the search path where the file was found, which may be a directory, or an archive. Even if there are multiple matches in different parts of the search path, only the first one found is used, just like when opening a file.
    … …  
    264313If you specify a fake directory that only exists as a mount point, it'll be associated with the first archive mounted there, even though that directory isn't necessarily contained in a real archive.
    265314
    266 ; (enumerateFiles dir) : Get a file listing of a search path's directory.
     315==== <procedure>(enumerate-files dir)</procedure>
     316
     317Get a file listing of a search path's directory.
    267318
    268319Matching directories are interpolated.
    … …  
    270321Feel free to sort the list however you like. We only promise there will be no duplicates, but not what order the final list will come back in.
    271322
    272 ; (exists filename) : Determine if a file exists in the search path.
     323==== <procedure>(exists filename)</procedure>
     324
     325Determine if a file exists in the search path.
    273326
    274327Reports true if there is an entry anywhere in the search path by the name of (filename).
    … …  
    276329Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, so you might end up further down in the search path than expected.
    277330
    278 ; (isDirectory filename) : Determine if a file in the search path is really a directory.
     331==== <procedure>(directory? filename)</procedure>
     332
     333Determine if a file in the search path is really a directory.
    279334
    280335Determine if the first occurence of (fname) in the search path is really a directory entry.
    … …  
    282337Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, so you might end up further down in the search path than expected.
    283338
    284 ; (isSymbolicLink filename) : Determine if a file in the search path is really a symbolic link.
     339==== <procedure>(symbolic-link? filename)</procedure>
     340
     341Determine if a file in the search path is really a symbolic link.
    285342
    286343Determine if the first occurence of (filename) in the search path is really a symbolic link.
    … …  
    288345Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, and as such, this function will always return 0 in that case.
    289346
    290 ; (getLastModTime filename) : Get the last modification time of a file.
     347==== <procedure>(get-last-mod-time filename)</procedure>
     348
     349Get the last modification time of a file.
    291350
    292351The modtime is returned as a number of seconds since the epoch (Jan 1, 1970). The exact derivation and accuracy of this time depends on the particular archiver. If there is no reasonable way to obtain this information for a particular archiver, or there was some sort of error, this function returns (-1).
    … …  
    294353=== Input/Output
    295354
    296 ; (openWrite filename) : Open a file for writing.
     355==== <procedure>(open-write filename)</procedure>
     356
     357Open a file for writing.
    297358
    298359Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, it is truncated to zero bytes, and the writing offset is set to the start.
    … …  
    300361Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, and opening a symlink with this function will fail in such a case.
    301362
    302 ; (openAppend filename) : Open a file for appending.
     363==== <procedure>(open-append filename)</procedure>
     364
     365Open a file for appending.
    303366
    304367Open a file for writing, in platform-independent notation and in relation to the write dir as the root of the writable filesystem. The specified file is created if it doesn't exist. If it does exist, the writing offset is set to the end of the file, so the first write will be the byte after the end.
    … …  
    306369Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, and opening a symlink with this function will fail in such a case.
    307370
    308 ; (openRead filename) : Open a file for reading.
     371==== <procedure>(open-read filename)</procedure>
     372
     373Open a file for reading.
    309374
    310375Open a file for reading, in platform-independent notation. The search path is checked one at a time until a matching file is found, in which case an abstract filehandle is associated with it, and reading may be done. The reading offset is set to the first byte of the file.
    … …  
    312377Note that entries that are symlinks are ignored if (permitSymbolicLinks #t) hasn't been called, and opening a symlink with this function will fail in such a case.
    313378
    314 ; (close handle) : Close a PhysicsFS filehandle.
     379==== <procedure>(close handle)</procedure>
     380
     381Close a PhysicsFS filehandle.
    315382
    316383This call is capable of failing if the operating system was buffering writes to the physical media, and, now forced to write those changes to physical media, can not store the data for some reason. In such a case, the filehandle stays open. A well-written program should ALWAYS check the return value from the close call in addition to every writing call!
    317384
    318 ; (read handle buffer objSize objCount) : Read data from a PhysicsFS filehandle
     385==== <procedure>(read handle buffer objSize objCount)</procedure>
     386
     387Read data from a PhysicsFS filehandle
    319388
    320389The file must be opened for reading.
    321390
    322 ; (write handle buffer objSize objCount) : Write data to a PhysicsFS filehandle
     391==== <procedure>(write handle buffer objSize objCount)</procedure>
     392
     393Write data to a PhysicsFS filehandle
    323394
    324395The file must be opened for writing.
    … …  
    326397=== File Positioning
    327398
    328 ; (eof handle) : Check for end-of-file state on a PhysicsFS filehandle.
     399==== <procedure>(eof handle)</procedure>
     400
     401Check for end-of-file state on a PhysicsFS filehandle.
    329402
    330403Determine if the end of file has been reached in a PhysicsFS filehandle.
    331404
    332 ; (tell handle) : Determine current position within a PhysicsFS filehandle.
    333 
    334 ; (seek handle pos) : Seek to a new position within a PhysicsFS filehandle.
     405==== <procedure>(tell handle)</procedure>
     406
     407Determine current position within a PhysicsFS filehandle.
     408
     409==== <procedure>(seek handle pos)</procedure>
     410
     411Seek to a new position within a PhysicsFS filehandle.
    335412
    336413The next read or write will occur at that place. Seeking past the beginning or end of the file is not allowed, and causes an error.
    337414
    338 ; (fileLength handle) : Get total length of a file in bytes.
     415==== <procedure>(file-length handle)</procedure>
     416
     417Get total length of a file in bytes.
    339418
    340419Note that if the file size can't be determined (since the archive is "streamed" or whatnot) than this will report (-1). Also note that if another process/thread is writing to this file at the same time, then the information this function supplies could be incorrect before you get it. Use with caution, or better yet, don't use at all.
    … …  
    342421=== Buffering
    343422
    344 ; (setBuffer handle bufsize) : Set up buffering for a PhysicsFS file handle.
     423==== <procedure>(set-buffer handle bufsize)</procedure>
     424
     425Set up buffering for a PhysicsFS file handle.
    345426
    346427Define an i/o buffer for a file handle. A memory block of (bufsize) bytes will be allocated and associated with (handle).
    347428
    348 For files opened for reading, up to (bufsize) bytes are read from (handle) and stored in the internal buffer. Calls to PHYSFS_read() will pull from this buffer until it is empty, and then refill it for more reading. Note that compressed files, like ZIP archives, will decompress while buffering, so this can be handy for offsetting CPU-intensive operations. The buffer isn't filled until you do your next read.
     429For files opened for reading, up to (bufsize) bytes are read from (handle) and stored in the internal buffer. Calls to (read) will pull from this buffer until it is empty, and then refill it for more reading. Note that compressed files, like ZIP archives, will decompress while buffering, so this can be handy for offsetting CPU-intensive operations. The buffer isn't filled until you do your next read.
    349430
    350431For files opened for writing, data will be buffered to memory until the buffer is full or the buffer is flushed. Closing a handle implicitly causes a flush...check your return values!
    … …  
    358439Please check the return value of this function! Failures can include not being able to seek backwards in a read-only file when removing the buffer, not being able to allocate the buffer, and not being able to flush the buffer to disk, among other unexpected problems.
    359440
    360 ; (flush handle) : Flush a buffered PhysicsFS file handle.
     441==== <procedure>(flush handle)</procedure>
     442
     443Flush a buffered PhysicsFS file handle.
    361444
    362445For buffered files opened for writing, this will put the current contents of the buffer to disk and flag the buffer as empty if possible.
    … …  
    366449=== Byte Ordering
    367450
    368 ; (swapSLE16 val) : Swap littleendian signed 16 to platform's native byte order.
     451==== <procedure>(swap-sle16 val)</procedure>
     452
     453Swap littleendian signed 16 to platform's native byte order.
    369454
    370455Take a 16-bit signed value in littleendian format and convert it to the platform's native byte order.
    371456
    372 ; (swapULE16 val) : Swap littleendian unsigned 16 to platform's native byte order.
     457==== <procedure>(swap-ule16 val)</procedure>
     458
     459Swap littleendian unsigned 16 to platform's native byte order.
    373460
    374461Take a 16-bit unsigned value in littleendian format and convert it to the platform's native byte order.
    375462
    376 ; (swapSLE32 val) : Swap littleendian signed 32 to platform's native byte order.
     463==== <procedure>(swap-sle32 val)</procedure>
     464
     465Swap littleendian signed 32 to platform's native byte order.
    377466
    378467Take a 32-bit signed value in littleendian format and convert it to the platform's native byte order.
    379468
    380 ; (swapULE32 val) : Swap littleendian unsigned 32 to platform's native byte order.
     469==== <procedure>(swap-ule32 val)</procedure>
     470
     471Swap littleendian unsigned 32 to platform's native byte order.
    381472
    382473Take a 32-bit unsigned value in littleendian format and convert it to the platform's native byte order.
    383474
    384 ; (swapSLE64 val) : Swap littleendian signed 64 to platform's native byte order.
     475==== <procedure>(swap-sle64 val)</procedure>
     476
     477Swap littleendian signed 64 to platform's native byte order.
    385478
    386479Take a 64-bit signed value in littleendian format and convert it to the platform's native byte order.
    387480
    388 ; (swapULE64 val) : Swap littleendian unsigned 64 to platform's native byte order.
     481==== <procedure>(swap-ule64 val)</procedure>
     482
     483Swap littleendian unsigned 64 to platform's native byte order.
    389484
    390485Take a 64-bit unsigned value in littleendian format and convert it to the platform's native byte order.
    391486
    392 ; (swapSBE16 val) : Swap bigendian signed 16 to platform's native byte order.
     487==== <procedure>(swap-sbe16 val)</procedure>
     488
     489Swap bigendian signed 16 to platform's native byte order.
    393490
    394491Take a 16-bit signed value in bigendian format and convert it to the platform's native byte order.
    395492
    396 ; (swapUBE16 val) : Swap bigendian unsigned 16 to platform's native byte order.
     493==== <procedure>(swap-ube16 val)</procedure>
     494
     495Swap bigendian unsigned 16 to platform's native byte order.
    397496
    398497Take a 16-bit unsigned value in bigendian format and convert it to the platform's native byte order.
    399498
    400 ; (swapSBE32 val) : Swap bigendian signed 32 to platform's native byte order.
     499==== <procedure>(swap-sbe32 val)</procedure>
     500
     501Swap bigendian signed 32 to platform's native byte order.
    401502
    402503Take a 32-bit signed value in bigendian format and convert it to the platform's native byte order.
    403504
    404 ; (swapUBE32 val) : Swap bigendian unsigned 32 to platform's native byte order.
     505==== <procedure>(swap-ube32 val)</procedure>
     506
     507Swap bigendian unsigned 32 to platform's native byte order.
    405508
    406509Take a 32-bit unsigned value in bigendian format and convert it to the platform's native byte order.
    407510
    408 ; (swapSBE64 val) : Swap bigendian signed 64 to platform's native byte order.
     511==== <procedure>(swap-sbe64 val)</procedure>
     512
     513Swap bigendian signed 64 to platform's native byte order.
    409514
    410515Take a 64-bit signed value in bigendian format and convert it to the platform's native byte order.
    411516
    412 ; (swapUBE64 val) : Swap bigendian unsigned 64 to platform's native byte order.
     517==== <procedure>(swap-ube64 val)</procedure>
     518
     519Swap bigendian unsigned 64 to platform's native byte order.
    413520
    414521Take a 64-bit unsigned value in bigendian format and convert it to the platform's native byte order.
    415522
    416 ; (readSLE16 file) : Read and convert a signed 16-bit littleendian value.
     523==== <procedure>(read-sle16 file)</procedure>
     524
     525Read and convert a signed 16-bit littleendian value.
    417526
    418527Convenience function. Read a signed 16-bit littleendian value from a file and convert it to the platform's native byte order.
    419528
    420 ; (readULE16 file) : Read and convert an unsigned 16-bit littleendian value.
     529==== <procedure>(read-ule16 file)</procedure>
     530
     531Read and convert an unsigned 16-bit littleendian value.
    421532
    422533Convenience function. Read an unsigned 16-bit littleendian value from a file and convert it to the platform's native byte order.
    423534
    424 ; (readSBE16 file) : Read and convert a signed 16-bit bigendian value.
     535==== <procedure>(read-sbe16 file)</procedure>
     536
     537Read and convert a signed 16-bit bigendian value.
    425538
    426539Convenience function. Read a signed 16-bit bigendian value from a file and convert it to the platform's native byte order.
    427540
    428 ; (readUBE16 file) : Read and convert an unsigned 16-bit bigendian value.
     541==== <procedure>(read-ube16 file)</procedure>
     542
     543Read and convert an unsigned 16-bit bigendian value.
    429544
    430545Convenience function. Read an unsigned 16-bit bigendian value from a file and convert it to the platform's native byte order.
    431546
    432 ; (readSLE32 file) : Read and convert a signed 32-bit littleendian value.
     547==== <procedure>(read-sle32 file)</procedure>
     548
     549Read and convert a signed 32-bit littleendian value.
    433550
    434551Convenience function. Read a signed 32-bit littleendian value from a file and convert it to the platform's native byte order.
    435552
    436 ; (readULE32 file) : Read and convert an unsigned 32-bit littleendian value.
     553==== <procedure>(read-ule32 file)</procedure>
     554
     555Read and convert an unsigned 32-bit littleendian value.
    437556
    438557Convenience function. Read an unsigned 32-bit littleendian value from a file and convert it to the platform's native byte order.
    439558
    440 ; (readSBE32 file) : Read and convert a signed 32-bit bigendian value.
     559==== <procedure>(read-sbe32 file)</procedure>
     560
     561Read and convert a signed 32-bit bigendian value.
    441562
    442563Convenience function. Read a signed 32-bit bigendian value from a file and convert it to the platform's native byte order.
    443564
    444 ; (readUBE32 file) : Read and convert an unsigned 32-bit bigendian value.
     565==== <procedure>(read-ube32 file)</procedure>
     566
     567Read and convert an unsigned 32-bit bigendian value.
    445568
    446569Convenience function. Read an unsigned 32-bit bigendian value from a file and convert it to the platform's native byte order.
    447570
    448 ; (readSLE64 file) : Read and convert a signed 64-bit littleendian value.
     571==== <procedure>(read-sle64 file)</procedure>
     572
     573Read and convert a signed 64-bit littleendian value.
    449574
    450575Convenience function. Read a signed 64-bit littleendian value from a file and convert it to the platform's native byte order.
    451576
    452 ; (readULE64 file) : Read and convert an unsigned 64-bit littleendian value.
     577==== <procedure>(read-ule64 file)</procedure>
     578
     579Read and convert an unsigned 64-bit littleendian value.
    453580
    454581Convenience function. Read an unsigned 64-bit littleendian value from a file and convert it to the platform's native byte order.
    455582
    456 ; (readSBE64 file) : Read and convert a signed 64-bit bigendian value.
     583==== <procedure>(read-sbe64 file)</procedure>
     584
     585Read and convert a signed 64-bit bigendian value.
    457586
    458587Convenience function. Read a signed 64-bit bigendian value from a file and convert it to the platform's native byte order.
    459588
    460 ; (readUBE64 file) : Read and convert an unsigned 64-bit bigendian value.
     589==== <procedure>(read-ube64 file)</procedure>
     590
     591Read and convert an unsigned 64-bit bigendian value.
    461592
    462593Convenience function. Read an unsigned 64-bit bigendian value from a file and convert it to the platform's native byte order.
    463594
    464 ; (writeSLE16 file val) : Convert and write a signed 16-bit littleendian value.
     595==== <procedure>(write-sle16 file val)</procedure>
     596
     597Convert and write a signed 16-bit littleendian value.
    465598
    466599Convenience function. Convert a signed 16-bit value from the platform's native byte order to littleendian and write it to a file.
    467600
    468 ; (writeULE16 file val) : Convert and write an unsigned 16-bit littleendian value.
     601==== <procedure>(write-ule16 file val)</procedure>
     602
     603Convert and write an unsigned 16-bit littleendian value.
    469604
    470605Convenience function. Convert an unsigned 16-bit value from the platform's native byte order to littleendian and write it to a file.
    471606
    472 ; (writeSBE16 file val) : Convert and write a signed 16-bit bigendian value.
     607==== <procedure>(write-sbe16 file val)</procedure>
     608
     609Convert and write a signed 16-bit bigendian value.
    473610
    474611Convenience function. Convert a signed 16-bit value from the platform's native byte order to bigendian and write it to a file.
    475612
    476 ; (writeUBE16 file val) : Convert and write an unsigned 16-bit bigendian value.
     613==== <procedure>(write-ube16 file val)</procedure>
     614
     615Convert and write an unsigned 16-bit bigendian value.
    477616
    478617Convenience function. Convert an unsigned 16-bit value from the platform's native byte order to bigendian and write it to a file.
    479618
    480 ; (writeSLE32 file val) : Convert and write a signed 32-bit littleendian value.
     619==== <procedure>(write-sle32 file val)</procedure>
     620
     621Convert and write a signed 32-bit littleendian value.
    481622
    482623Convenience function. Convert a signed 32-bit value from the platform's native byte order to littleendian and write it to a file.
    483624
    484 ; (writeULE32 file val) : Convert and write an unsigned 32-bit littleendian value.
     625==== <procedure>(write-ule32 file val)</procedure>
     626
     627Convert and write an unsigned 32-bit littleendian value.
    485628
    486629Convenience function. Convert an unsigned 32-bit value from the platform's native byte order to littleendian and write it to a file.
    487630
    488 ; (writeSBE32 file val) : Convert and write a signed 32-bit bigendian value.
     631==== <procedure>(write-sbe32 file val)</procedure>
     632
     633Convert and write a signed 32-bit bigendian value.
    489634
    490635Convenience function. Convert a signed 32-bit value from the platform's native byte order to bigendian and write it to a file.
    491636
    492 ; (writeUBE32 file val) : Convert and write an unsigned 32-bit bigendian value.
     637==== <procedure>(write-ube32 file val)</procedure>
     638
     639Convert and write an unsigned 32-bit bigendian value.
    493640
    494641Convenience function. Convert an unsigned 32-bit value from the platform's native byte order to bigendian and write it to a file.
    495642
    496 ; (writeSLE64 file val) : Convert and write a signed 64-bit littleendian value.
     643==== <procedure>(write-sle64 file val)</procedure>
     644
     645Convert and write a signed 64-bit littleendian value.
    497646
    498647Convenience function. Convert a signed 64-bit value from the platform's native byte order to littleendian and write it to a file.
    499648
    500 ; (writeULE64 file val) : Convert and write an unsigned 64-bit littleendian value.
     649==== <procedure>(write-ule64 file val)</procedure>
     650
     651Convert and write an unsigned 64-bit littleendian value.
    501652
    502653Convenience function. Convert an unsigned 64-bit value from the platform's native byte order to littleendian and write it to a file.
    503654
    504 ; (writeSBE64 file val) : Convert and write a signed 64-bit bigending value.
     655==== <procedure>(write-sbe64 file val)</procedure>
     656
     657Convert and write a signed 64-bit bigending value.
    505658
    506659Convenience function. Convert a signed 64-bit value from the platform's native byte order to bigendian and write it to a file.
    507660
    508 ; (writeUBE64 file val) : Convert and write an unsigned 64-bit bigendian value.
     661==== <procedure>(write-ube64 file val)</procedure>
     662
     663Convert and write an unsigned 64-bit bigendian value.
    509664
    510665Convenience function. Convert an unsigned 64-bit value from the platform's native byte order to bigendian and write it to a file.
    … …  
    512667== PhysicsFS 2.0 Functionality
    513668
    514 ; (isInit) : Determine if the PhysicsFS library is initialized.
     669==== <procedure>(init?)</procedure>
     670
     671Determine if the PhysicsFS library is initialized.
    515672
    516673Once (init) returns successfully, this will return non-zero. Before a successful (init) and after (deinit) returns successfully, this will return zero. This function is safe to call at any time.
    517674
    518 ; (symbolicLinksPermitted) : Determine if the symbolic links are permitted.
    519 
    520 This reports the setting from the last call to (permitSymbolicLinks). If (permitSymbolicLinks) hasn't been called since the library was last initialized, symbolic links are implicitly disabled.
    521 
    522 ; (mount newDir mountPoint appendToPath) : Add an archive or directory to the search path.
     675==== <procedure>(symbolic-links-permitted)</procedure>
     676
     677Determine if the symbolic links are permitted.
     678
     679This reports the setting from the last call to (permit-symbolic-links). If (permitSymbolicLinks) hasn't been called since the library was last initialized, symbolic links are implicitly disabled.
     680
     681==== <procedure>(mount newDir mountPoint appendToPath)</procedure>
     682
     683Add an archive or directory to the search path.
    523684
    524685If this is a duplicate, the entry is not added again, even though the function succeeds. You may not add the same archive to two different mountpoints: duplicate checking is done against the archive and not the mountpoint.
    … …  
    528689The mountpoint does not need to exist prior to mounting, which is different than those familiar with the Unix concept of "mounting" may not expect. As well, more than one archive can be mounted to the same mountpoint, or mountpoints and archive contents can overlap...the interpolation mechanism still functions as usual.
    529690
    530 ; (getMountPoint dir) : Determine a mounted archive's mountpoint.
     691==== <procedure>(getMountPoint dir)</procedure>
     692
     693Determine a mounted archive's mountpoint.
    531694
    532695You give this function the name of an archive or dir you successfully added to the search path, and it reports the location in the interpolated tree where it is mounted. Files mounted with a NULL mountpoint or through (addToSearchPath) will report "/". The return value is READ ONLY and valid until the archive is removed from the search path.
    … …  
    534697=== UTF8 Functions
    535698
    536 ; (utf8FromUcs4 src len) : Convert a UCS-4 string to a UTF-8 string.
     699==== <procedure>(utf8-from-ucs4 src len)</procedure>
     700
     701Convert a UCS-4 string to a UTF-8 string.
    537702
    538703UCS-4 strings are 32-bits per character: \c wchar_t on Unix.
    539704
    540 ; (utf8ToUcs4 src len) : Convert a UTF-8 string to a UCS-4 string.
     705==== <procedure>(utf8-to-ucs4 src len)</procedure>
     706
     707Convert a UTF-8 string to a UCS-4 string.
    541708
    542709UCS-4 strings are 32-bits per character: \c wchar_t on Unix.
    543710
    544 ; (utf8FromUcs2 src len) : Convert a UCS-2 string to a UTF-8 string.
     711==== <procedure>(utf8-from-ucs2 src len)</procedure>
     712
     713Convert a UCS-2 string to a UTF-8 string.
    545714
    546715UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building with Unicode support.
    … …  
    548717Please note that UCS-2 is not UTF-16; we do not support the "surrogate" values at this time.
    549718
    550 ; (utf8ToUcs2 src len) : Convert a UTF-8 string to a UCS-2 string.
     719==== <procedure>(utf8-to-ucs2 src len)</procedure>
     720
     721Convert a UTF-8 string to a UCS-2 string.
    551722
    552723UCS-2 strings are 16-bits per character: \c TCHAR on Windows, when building with Unicode support.
    … …  
    554725Please note that UCS-2 is not UTF-16; we do not support the "surrogate" values at this time.
    555726
    556 ; (utf8FromLatin1 src len) : Convert a UTF-8 string to a Latin1 string.
     727==== <procedure>(utf8-from-latin1 src len)</procedure>
     728
     729Convert a UTF-8 string to a Latin1 string.
    557730
    558731Latin1 strings are 8-bits per character: a popular "high ASCII" encoding.
    … …  
    560733Please note that we do not supply a UTF-8 to Latin1 converter, since Latin1 can't express most Unicode codepoints. It's a legacy encoding; you should be converting away from it at all times.
    561734
     735=== Convenience Functions
     736
     737==== <procedure>(read-from-file file-name)</procedure>
     738
     739Assuming that PhysicsFS has been initialized and that a location has been mounted, this function will read an entire file into a <type>blob</type>.
     740
     741Throws errors if the parameter is not a string, or if the declared file name cannot be found, or if PhysicsFS is not initialized.
     742
     743==== <procedure>(write-to-file file-name data)</procedure>
     744
     745Assuming that PhysicsFS has been initialized and that a mount point is available; given a file name and a <type>blob</type> this function will write the entire contents of the blob to the file.
     746
     747Throws errors if the parameters are incorrect, or if PhysicsFS is not initialized.
     748
     749== Known Issues
     750
     751* 64-bit return values for foreign bindings are not supported by Chicken at the moment, and as such the read-foo64 bindings, and others, aren't actually available.
     752
    562753== Author
    563754
    … …  
    566757== Version history
    567758
     759; 2.0 : Switched from camel case to hyphenated style, added write-to-file and read-from-file
    568760; 1.0 : First release, interfaces conform to The Scheme Way
    569761; 0.1 : Alpha release, version with tests coming soon
Note: See TracChangeset for help on using the changeset viewer.