r346 - trunk
DONOTREPLY at icculus.org
DONOTREPLY at icculus.org
Mon Sep 24 22:24:31 EDT 2007
Author: icculus
Date: 2007-09-24 22:24:31 -0400 (Mon, 24 Sep 2007)
New Revision: 346
Modified:
trunk/platform.h
Log:
Documented some of the platform layer interfaces.
Modified: trunk/platform.h
===================================================================
--- trunk/platform.h 2007-09-25 02:24:10 UTC (rev 345)
+++ trunk/platform.h 2007-09-25 02:24:31 UTC (rev 346)
@@ -54,7 +54,10 @@
// on failure. The caller is responsible for freeing the returned pointer!
char *MojoPlatform_readlink(const char *linkname);
-// !!! FIXME: comment me.
+// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
+// !!! FIXME: and Extended Attributes need more.
+// Create a directory in the physical filesystem, with (perms) permissions.
+// returns true if directory is created, false otherwise.
boolean MojoPlatform_mkdir(const char *path, uint16 perms);
// Move a file to a new name. This has to be a fast (if not atomic) operation,
@@ -63,31 +66,55 @@
// Returns true on successful rename, false otherwise.
boolean MojoPlatform_rename(const char *src, const char *dst);
-// !!! FIXME: comment me.
+// Determine if dir/fname exists in the native filesystem. It doesn't matter
+// if it's a directory, file, symlink, etc, we're just looking for the
+// existance of the entry itself. (fname) may be NULL, in which case,
+// (dir) contains the whole path, otherwise, the platform layer needs to
+// build the path: (on Unix: dir/path, on Windows: dir\\path, etc).
+// This is a convenience thing for the caller.
+// Returns true if path in question exists, false otherwise.
boolean MojoPlatform_exists(const char *dir, const char *fname);
-// !!! FIXME: comment me.
+// Returns true if (fname) in the native filesystem is writable. If (fname)
+// is a directory, this means that the contents of the directory can be
+// added to (create files, delete files, etc). If (fname) is a file, this
+// means that this process has write access to the file.
+// Returns false if (fname) isn't writable.
boolean MojoPlatform_writable(const char *fname);
-// !!! FIXME: comment me.
+// Returns true if (dir) is a directory in the physical filesystem, false
+// otherwise (including if (dir) doesn't exist). Don't follow symlinks.
boolean MojoPlatform_isdir(const char *dir);
-// !!! FIXME: comment me.
+// Returns true if (fname) is a symlink in the physical filesystem, false
+// otherwise (including if (fname) doesn't exist). Don't follow symlinks.
boolean MojoPlatform_issymlink(const char *fname);
-// !!! FIXME: comment me.
+// Returns true if (fname) is a regular file in the physical filesystem, false
+// otherwise (including if (fname) doesn't exist). Don't follow symlinks.
boolean MojoPlatform_isfile(const char *fname);
-// !!! FIXME: comment me.
+// Returns size, in bytes, of the file (fname) in the physical filesystem.
+// Return -1 if file is missing or not a file. Don't follow symlinks.
int64 MojoPlatform_filesize(const char *fname);
+// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
+// !!! FIXME: and Extended Attributes need more.
// !!! FIXME: comment me.
boolean MojoPlatform_perms(const char *fname, uint16 *p);
+// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
+// !!! FIXME: and Extended Attributes need more.
// !!! FIXME: comment me.
boolean MojoPlatform_chmod(const char *fname, uint16 p);
-// !!! FIXME: comment me.
+// Try to locate a specific piece of media (usually an inserted CD or DVD).
+// (uniquefile) is a path that should exist on the media; its presence
+// should uniquely identify the media.
+// Returns the path of the media's mount point in the physical filesystem
+// (something like "E:\\" on Windows or "/mnt/cdrom" on Unix), or NULL if
+// the media isn't found (needed disc isn't inserted, etc).
+// Caller must free return value!
char *MojoPlatform_findMedia(const char *uniquefile);
// Flag values for MojoPlatform_fopen().
@@ -108,24 +135,45 @@
MOJOSEEK_END
} MojoFileSeek;
-// !!! FIXME: comment me.
+// !!! FIXME: we really can't do this in a 16-bit value...non-Unix platforms
+// !!! FIXME: and Extended Attributes need more.
+// Open file (fname). This wraps a subset of the Unix open() syscall. Use
+// MojoFileFlags for (flags). If creating a file, use (mode) for the new
+// file's permissions.
+// Returns an opaque handle on success, NULL on error. Caller must free
+// handle with MojoPlatform_close() when done with it.
void *MojoPlatform_open(const char *fname, uint32 flags, uint16 mode);
-// !!! FIXME: comment me.
+
+// Read (bytes) bytes from (fd) into (buf). This wraps the Unix read() syscall.
+// Returns number of bytes read, -1 on error.
int64 MojoPlatform_read(void *fd, void *buf, uint32 bytes);
-// !!! FIXME: comment me.
+
+// Write (bytes) bytes from (buf) into (fd). This wraps the Unix write()
+// syscall. Returns number of bytes read, -1 on error.
int64 MojoPlatform_write(void *fd, const void *buf, uint32 bytes);
-// !!! FIXME: comment me.
+
+// Reports byte offset of file pointer in (fd), or -1 on error.
int64 MojoPlatform_tell(void *fd);
-// !!! FIXME: comment me.
+
+// Seek to (offset) byte offset of file pointer in (fd), relative to (whence).
+// This wraps the Unix lseek() syscall. Returns byte offset from the start
+// of the file, -1 on error.
int64 MojoPlatform_seek(void *fd, int64 offset, MojoFileSeek whence);
-// !!! FIXME: comment me.
+
+// Get the size, in bytes, of a file, referenced by its opaque handle.
+// (This pulls the data through an fstat() on Unix.) Retuns -1 on error.
int64 MojoPlatform_flen(void *fd);
-// !!! FIXME: comment me.
+
+// Force any pending data to disk, returns true on success, false if there
+// was an i/o error.
boolean MojoPlatform_flush(void *fd);
-// !!! FIXME: comment me.
+
+// Free any resources associated with (fd), flushing any pending data to disk,
+// and closing the file. (fd) becomes invalid after this call returns
+// successfully. This wraps the Unix close() syscall. Returns true on
+// success, false on i/o error.
boolean MojoPlatform_close(void *fd);
-
// Enumerate a directory. Returns an opaque pointer that can be used with
// repeated calls to MojoPlatform_readdir() to enumerate the names of
// directory entries. Returns NULL on error. Non-NULL values should be passed
More information about the mojosetup-commits
mailing list