From 9e46f8532580ad6144a3aa31b74775a99b7f3835 Mon Sep 17 00:00:00 2001 From: Elliot Nunn Date: Thu, 20 Sep 2018 09:03:33 +0800 Subject: [PATCH] ripped documentation --- main.c | 585 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 548 insertions(+), 37 deletions(-) diff --git a/main.c b/main.c index 99974e3..0cb59a6 100644 --- a/main.c +++ b/main.c @@ -21,6 +21,34 @@ #define GETERR (hfs_error ? hfs_error : "unknown error") +static const char doc_mount[] = + "hfsvol *hfs_mount(const char *path, int pnum, int flags);\n" + "\n" + "This routine attempts to open an HFS volume from a source pathname. The\n" + "given `pnum' indicates which ordinal HFS partition is to be mounted,\n" + "or can be 0 to indicate the entire medium should be mounted (ignoring\n" + "any partition structure). If this value is not 0, the requested\n" + "partition must exist.\n" + "\n" + "The `flags' argument specifies how the volume should be mounted.\n" + "HFS_MODE_RDONLY means the volume should be mounted read-only.\n" + "HFS_MODE_RDWR means the volume must be opened read/write. HFS_MODE_ANY\n" + "means the volume can be mounted either read-only or read/write, with\n" + "preference for the latter.\n" + "\n" + "The `flags' argument may also specify volume options. HFS_OPT_NOCACHE\n" + "means not to perform any internal block caching, such as would be\n" + "unnecessary for a volume residing in RAM, or if the associated overhead\n" + "is not desired. HFS_OPT_ZERO means that newly-allocated blocks should be\n" + "zero-initialized before use, primarily as a security feature for systems\n" + "on which blocks may otherwise contain random data. Neither of these\n" + "options should normally be necessary, and both may affect performance.\n" + "\n" + "If an error occurs, this function returns NULL. Otherwise a pointer to a\n" + "volume structure is returned. This pointer is used to access the volume\n" + "and must eventually be passed to hfs_umount() to flush and close the\n" + "volume and free all associated memory."; + static PyObject *wrap_mount(PyObject *self, PyObject *args) { char *arg_path; int arg_pnum; int arg_flags; @@ -32,6 +60,16 @@ static PyObject *wrap_mount(PyObject *self, PyObject *args) return PyCapsule_New((void *)ret, NAME_HFSVOL, NULL); } +static const char doc_flush[] = + "int hfs_flush(hfsvol *vol);\n" + "\n" + "This routine causes all pending changes to be flushed to an HFS volume.\n" + "If a volume is kept open for a long period of time, it would be wise\n" + "to call this periodically to avoid corrupting the volume due to\n" + "unforeseen circumstances (power failure, floppy eject, etc.)\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_flush(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; @@ -45,12 +83,33 @@ static PyObject *wrap_flush(PyObject *self, PyObject *args) return Py_None; } +static const char doc_flushall[] = + "void hfs_flushall(void);\n" + "\n" + "This routine is similar to hfs_flush() except that all mounted volumes\n" + "are flushed, and errors are not reported."; + static PyObject *wrap_flushall(PyObject *self, PyObject *args) { hfs_flushall(); return Py_None; } +static const char doc_umount[] = + "int hfs_umount(hfsvol *vol);\n" + "\n" + "The specified HFS volume is unmounted; all open files and directories\n" + "on the volume are closed, all pending changes to the volume are\n" + "flushed, and all memory allocated for the volume is freed.\n" + "\n" + "All volumes opened with hfs_mount() must eventually be closed with\n" + "hfs_umount(), or they will risk corruption.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0.\n" + "In either case, the volume structure pointer will become invalid, as\n" + "will all pointers to open file or directory structures associated with\n" + "the volume."; + static PyObject *wrap_umount(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; @@ -64,12 +123,34 @@ static PyObject *wrap_umount(PyObject *self, PyObject *args) return Py_None; } +static const char doc_umountall[] = + "void hfs_umountall(void);\n" + "\n" + "This routine is similar to hfs_umount() except that all mounted volumes\n" + "are closed, and errors are not reported.\n" + "\n" + "This routine may be useful to call just before a process terminates to\n" + "make sure any remaining open volumes are properly closed."; + static PyObject *wrap_umountall(PyObject *self, PyObject *args) { hfs_umountall(); return Py_None; } +static const char doc_getvol[] = + "hfsvol *hfs_getvol(const char *name);\n" + "\n" + "This routines searches all mounted volumes for one having the given\n" + "`name', and returns its volume structure pointer. If more than one\n" + "volume have the same name, the most recently mounted one is returned. If\n" + "no volume matches the given name, a NULL pointer is returned.\n" + "\n" + "The given `name' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If a NULL pointer is passed to this routine, the current volume is\n" + "returned, if any."; + static PyObject *wrap_getvol(PyObject *self, PyObject *args) { char *arg_vol; @@ -82,6 +163,13 @@ static PyObject *wrap_getvol(PyObject *self, PyObject *args) return PyCapsule_New((void *)ret, NAME_HFSVOL, NULL); } +static const char doc_setvol[] = + "void hfs_setvol(hfsvol *vol);\n" + "\n" + "The routine changes the \"current\" volume. Most HFS routines will accept\n" + "a NULL volume pointer to mean the current volume; by default, the\n" + "current volume is the last one which was mounted."; + static PyObject *wrap_setvol(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; @@ -94,6 +182,16 @@ static PyObject *wrap_setvol(PyObject *self, PyObject *args) return Py_None; } +static const char doc_vstat[] = + "int hfs_vstat(hfsvol *vol, hfsvolent *ent);\n" + "\n" + "This routine fills the volume entity structure `*ent' with information\n" + "about a mounted volume. The fields of the structure are defined in\n" + "the hfs.h header file.\n" + "\n" + "This routine returns 0 unless a NULL pointer is passed for the volume\n" + "and no volume is current, in which case it returns -1."; + static PyObject *wrap_vstat(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; @@ -108,6 +206,20 @@ static PyObject *wrap_vstat(PyObject *self, PyObject *args) return Py_BuildValue("y#", (char *)(&ret_volent), sizeof(ret_volent)); } +static const char doc_vsetattr[] = + "int hfs_vsetattr(hfsvol *vol, hfsvolent *ent);\n" + "\n" + "This routine allows some attributes of a volume to be changed. The\n" + "attributes which may be changed are: ent->clumpsz, ent->crdate,\n" + "ent->mddate, ent->bkdate, and ent->blessed. Note that the default file\n" + "clump size may only be changed to be a multiple of the volume's\n" + "allocation block size, and the \"blessed\" folder must either be 0 or a\n" + "valid folder CNID.\n" + "\n" + "To change the volume's name, use hfs_rename().\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_vsetattr(PyObject *self, PyObject *args) // problems { hfsvol *arg_vol; PyObject *arg_vol_c; hfsvolent *arg_ent; Py_ssize_t arg_ent_len; @@ -123,6 +235,16 @@ static PyObject *wrap_vsetattr(PyObject *self, PyObject *args) // problems return Py_None; } +static const char doc_chdir[] = + "int hfs_chdir(hfsvol *vol, const char *path);\n" + "\n" + "The \"current working directory\" for the given volume is changed.\n" + "`path' can be either a relative or absolute HFS path.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_chdir(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -136,6 +258,13 @@ static PyObject *wrap_chdir(PyObject *self, PyObject *args) return Py_None; } +static const char doc_getcwd[] = + "long hfs_getcwd(hfsvol *vol);\n" + "\n" + "The internal directory ID of the current working directory for the\n" + "given volume is returned. This value is typically only useful for\n" + "passing to hfs_setcwd() or hfs_dirinfo()."; + static PyObject *wrap_getcwd(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; @@ -147,6 +276,14 @@ static PyObject *wrap_getcwd(PyObject *self, PyObject *args) return Py_BuildValue("l", hfs_getcwd(arg_vol)); } +static const char doc_setcwd[] = + "int hfs_setcwd(hfsvol *vol, long id);\n" + "\n" + "This routine changes the current working directory for the given\n" + "volume. A directory must exist with the given id.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_setcwd(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; long arg_id; @@ -160,6 +297,23 @@ static PyObject *wrap_setcwd(PyObject *self, PyObject *args) return Py_None; } +static const char doc_dirinfo[] = + "int hfs_dirinfo(hfsvol *vol, long *id, char *name);\n" + "\n" + "This function looks up the given directory ID `*id' and stores in its\n" + "place the directory ID of its parent. If `name' is not NULL, the name\n" + "of the (child) directory is also stored in the buffer pointed to by it,\n" + "which must be at least HFS_MAX_FLEN + 1 (32) bytes long.\n" + "\n" + "The string `name' will be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0.\n" + "\n" + "This function can be called repeatedly to construct a full pathname\n" + "to the current working directory. The root directory of a volume\n" + "always has a directory ID of HFS_CNID_ROOTDIR, and a pseudo-parent ID\n" + "of HFS_CNID_ROOTPAR."; + static PyObject *wrap_dirinfo(PyObject *self, PyObject *args) // returns name in bytes object! { hfsvol *arg_vol; PyObject *arg_vol_c; unsigned long argret_id; @@ -174,6 +328,22 @@ static PyObject *wrap_dirinfo(PyObject *self, PyObject *args) // returns name in return Py_BuildValue("ly", argret_id, ret_name); } +static const char doc_opendir[] = + "hfsdir *hfs_opendir(hfsvol *vol, const char *path);\n" + "\n" + "This function prepares to read the contents of a directory. `path'\n" + "must be either an absolute or relative pathname to the desired HFS\n" + "directory. As a special case, if `path' is an empty string, a\n" + "\"meta-directory\" will be opened containing the root directories from\n" + "all of the currently mounted volumes.\n" + "\n" + "The string `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "This function returns a pointer which must be passed to the other\n" + "directory-related routines to read the directory.\n" + "\n" + "If an error occurs, this function returns a NULL pointer."; + static PyObject *wrap_opendir(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -188,6 +358,18 @@ static PyObject *wrap_opendir(PyObject *self, PyObject *args) return PyCapsule_New((void *)ret, NAME_HFSDIR, NULL); } +static const char doc_readdir[] = + "int hfs_readdir(hfsdir *dir, hfsdirent *ent);\n" + "\n" + "This routine fills the directory entity structure `*ent' with\n" + "information about the next item in the given open directory. The\n" + "fields of the structure are defined in the hfs.h header file.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0.\n" + "\n" + "When no more items occur in the directory, this function returns -1\n" + "and sets `errno' to ENOENT."; + static PyObject *wrap_readdir(PyObject *self, PyObject *args) { hfsdir *arg_dir; PyObject *arg_dir_c; @@ -204,6 +386,15 @@ static PyObject *wrap_readdir(PyObject *self, PyObject *args) return Py_BuildValue("y#", (char *)(&ret_ent), sizeof(ret_ent)); } +static const char doc_closedir[] = + "int hfs_closedir(hfsdir *dir);\n" + "\n" + "This function closes an open directory and frees all associated\n" + "memory.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0.\n" + "In either case, the directory structure pointer will no longer be valid."; + static PyObject *wrap_closedir(PyObject *self, PyObject *args) { hfsdir *arg_dir; PyObject *arg_dir_c; @@ -217,6 +408,21 @@ static PyObject *wrap_closedir(PyObject *self, PyObject *args) return Py_None; } +static const char doc_create[] = + "hfsfile *hfs_create(hfsvol *vol, const char *path,\n" + " const char *type, const char *creator);\n" + "\n" + "This routine creates a new, empty file with the given path, type, and\n" + "creator. The type and creator must be strings of length 4, and have\n" + "particular meaning under MacOS.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If the creation is successful, the file is opened and a pointer to a\n" + "file structure is returned, the same as if hfs_open() had been called.\n" + "\n" + "If an error occurs, this function returns a NULL pointer."; + static PyObject *wrap_create(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -235,6 +441,20 @@ static PyObject *wrap_create(PyObject *self, PyObject *args) return PyCapsule_New((void *)ret, NAME_HFSFILE, NULL); } +static const char doc_open[] = + "hfsfile *hfs_open(hfsvol *vol, const char *path);\n" + "\n" + "This function opens an HFS file in preparation for I/O. Both forks of\n" + "the file may be manipulated once the file is opened; hfs_setfork() is\n" + "used to select the current fork. By default, the data fork is current.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "A pointer to a file structure is returned. This pointer should be\n" + "passed to other routines to manipulate the file.\n" + "\n" + "If an error occurs, this function returns a NULL pointer."; + static PyObject *wrap_open(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -249,6 +469,27 @@ static PyObject *wrap_open(PyObject *self, PyObject *args) return PyCapsule_New((void *)ret, NAME_HFSFILE, NULL); } +static const char doc_setfork[] = + "int hfs_setfork(hfsfile *file, int fork);\n" + "\n" + "This routine selects the current fork in an open file for I/O. HFS\n" + "files have two forks, data and resource. Resource forks normally contain\n" + "structured data, although these HFS routines make no distinction\n" + "between forks when reading or writing. It is up to higher-level\n" + "applications to make sense of the information read or written from\n" + "either fork.\n" + "\n" + "If 0 is passed to this routine, the data fork is selected. Otherwise\n" + "the resource fork is selected. The seek pointer for the file is\n" + "automatically reset to the beginning of the newly selected fork.\n" + "\n" + "As a side effect, this routine causes any excess disk blocks allocated\n" + "for the fork which was current before the call to be freed; normally\n" + "extra blocks are allocated during file writes to promote contiguity.\n" + "This routine will return -1 if an error occurs in this process;\n" + "otherwise it will return 0. The current fork will have been changed\n" + "regardless."; + static PyObject *wrap_setfork(PyObject *self, PyObject *args) { hfsfile *arg_file; PyObject *arg_file_c; int arg_fork; @@ -262,6 +503,14 @@ static PyObject *wrap_setfork(PyObject *self, PyObject *args) return Py_None; } +static const char doc_getfork[] = + "int hfs_getfork(hfsfile *file);\n" + "\n" + "This routine returns an indication of which fork is currently active\n" + "for I/O operations on the given file. If 0 is returned, the data fork\n" + "is selected. Otherwise the resource fork is selected.\n" + ""; + static PyObject *wrap_getfork(PyObject *self, PyObject *args) { hfsfile *arg_file; PyObject *arg_file_c; @@ -273,6 +522,20 @@ static PyObject *wrap_getfork(PyObject *self, PyObject *args) return Py_BuildValue("i", hfs_getfork(arg_file)); } +static const char doc_read[] = + "long hfs_read(hfsfile *file, void *ptr, unsigned long len);\n" + "\n" + "This routine reads up to `len' bytes from the current fork of an HFS\n" + "file and places them into the buffer pointed to by `ptr' (which must be\n" + "at least `len' bytes long.) The number of bytes actually read is\n" + "returned, and may be less than `len' if the end of the file is reached.\n" + "\n" + "If this routine returns 0, there is no more data to be read from the\n" + "file. If an error occurs, this routine will return -1.\n" + "\n" + "It is most efficient to read data in multiples of HFS_BLOCKSZ byte\n" + "blocks at a time."; + static PyObject *wrap_read(PyObject *self, PyObject *args) // pass in a bytearray and get it shrunk! { hfsfile *arg_file; PyObject *arg_file_c; PyObject *arg_bytearray; @@ -288,6 +551,20 @@ static PyObject *wrap_read(PyObject *self, PyObject *args) // pass in a bytearra return Py_None; } +static const char doc_write[] = + "long hfs_write(hfsfile *file, const void *ptr, unsigned long len);\n" + "\n" + "This routine writes up to `len' bytes of data to the current fork of an\n" + "HFS file from the buffer pointed to by `ptr'. The number of bytes\n" + "actually written is returned. If an error occurs, this routine will\n" + "return -1.\n" + "\n" + "If the end of the file is reached before all bytes have been written,\n" + "the file is automatically extended.\n" + "\n" + "It is most efficient to write data in multiples of HFS_BLOCKSZ byte\n" + "blocks at a time."; + static PyObject *wrap_write(PyObject *self, PyObject *args) // pass in a bytearray and get it shrunk! { hfsfile *arg_file; PyObject *arg_file_c; PyObject *arg_bytes; Py_ssize_t arg_bytes_len; @@ -302,6 +579,18 @@ static PyObject *wrap_write(PyObject *self, PyObject *args) // pass in a bytearr return Py_BuildValue("l", byteswritten); } +static const char doc_truncate[] = + "int hfs_truncate(hfsfile *file, unsigned long len);\n" + "\n" + "This routine causes the current fork of the specified open file to be\n" + "truncated to at most `len' bytes.\n" + "\n" + "The disk blocks associated with the freed portion of the file are not\n" + "actually deallocated until either the current fork is changed or the\n" + "file is closed.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_truncate(PyObject *self, PyObject *args) // pass in a bytearray and get it shrunk! { hfsfile *arg_file; PyObject *arg_file_c; unsigned long arg_len; @@ -315,6 +604,29 @@ static PyObject *wrap_truncate(PyObject *self, PyObject *args) // pass in a byte return Py_None; } +static const char doc_seek[] = + "long hfs_seek(hfsfile *file, long offset, int from);\n" + "\n" + "This routine changes the current seek pointer for the specified open\n" + "file. This pointer determines where the next call to hfs_read() or\n" + "hfs_write() will read or write data within the current fork.\n" + "\n" + "If `from' is HFS_SEEK_SET, the pointer is set to the absolute position\n" + "given by `offset'.\n" + "\n" + "If `from' is HFS_SEEK_CUR, the pointer is offset from its current\n" + "position by the amount `offset'. Positive offsets seek forward; negative\n" + "offsets seek backward.\n" + "\n" + "If `from' is HFS_SEEK_END, the pointer is offset from the end of the\n" + "file by the amount `offset', which ought not be positive.\n" + "\n" + "It is not presently possible to set the seek pointer beyond the logical\n" + "end of the file.\n" + "\n" + "The new absolute position of the seek pointer is returned, unless an\n" + "invalid argument was specified, in which case -1 is returned."; + static PyObject *wrap_seek(PyObject *self, PyObject *args) // pass in a bytearray and get it shrunk! { hfsfile *arg_file; PyObject *arg_file_c; long arg_offset; int arg_from; @@ -329,6 +641,17 @@ static PyObject *wrap_seek(PyObject *self, PyObject *args) // pass in a bytearra return Py_BuildValue("l", absloc); } +static const char doc_close[] = + "int hfs_close(hfsfile *file);\n" + "\n" + "This routine causes all pending changes to the specified file to be\n" + "flushed, and all storage associated with the file structure to be\n" + "freed. Any excess disk blocks associated with the file are also\n" + "deallocated at this time.\n" + "\n" + "If an error occurs, this routine returns -1. Otherwise it returns 0.\n" + "In either case, the file structure pointer will no longer be valid."; + static PyObject *wrap_close(PyObject *self, PyObject *args) // pass in a bytearray and get it shrunk! { hfsfile *arg_file; PyObject *arg_file_c; @@ -342,6 +665,19 @@ static PyObject *wrap_close(PyObject *self, PyObject *args) // pass in a bytearr return Py_None; } +static const char doc_stat[] = + "int hfs_stat(hfsvol *vol, const char *path, hfsdirent *ent);\n" + "\n" + "This routine fills the directory entity structure `*ent' with\n" + "information about the file or directory specified by `path' on the\n" + "given volume. The fields of the structure are defined in the hfs.h\n" + "header file.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If there is no such path, or if another error occurs, this routine\n" + "returns -1. Otherwise it returns 0."; + static PyObject *wrap_stat(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -356,6 +692,14 @@ static PyObject *wrap_stat(PyObject *self, PyObject *args) return Py_BuildValue("y#", (char *)(&ret_ent), sizeof(ret_ent)); } +static const char doc_fstat[] = + "int hfs_fstat(hfsfile *file, hfsdirent *ent);\n" + "\n" + "This routine is similar to hfs_stat() except it returns information\n" + "about a file that is already open.\n" + "\n" + "If an error occurs, this routine returns -1. Otherwise it returns 0."; + static PyObject *wrap_fstat(PyObject *self, PyObject *args) { hfsfile *arg_file; PyObject *arg_file_c; @@ -370,6 +714,19 @@ static PyObject *wrap_fstat(PyObject *self, PyObject *args) return Py_BuildValue("y#", (char *)(&ret_ent), sizeof(ret_ent)); } +static const char doc_setattr[] = + "int hfs_setattr(hfsvol *vol, const char *path, const hfsdirent *ent);\n" + "\n" + "This routine changes various attributes of an existing file or\n" + "directory. The attributes which may be changed are: ent->crdate,\n" + "ent->mddate, ent->bkdate, ent->fdflags, ent->fdlocation,\n" + "ent->u.file.type, ent->u.file.creator, and ent->u.dir.rect. Also, the\n" + "locked status of a file may be changed with ent->flags & HFS_ISLOCKED.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this routine returns -1. Otherwise it returns 0."; + static PyObject *wrap_setattr(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; hfsdirent *arg_ent; Py_ssize_t arg_ent_len; @@ -385,6 +742,14 @@ static PyObject *wrap_setattr(PyObject *self, PyObject *args) return Py_None; } +static const char doc_fsetattr[] = + "int hfs_fsetattr(hfsfile *file, const hfsdirent *ent);\n" + "\n" + "This routine is similar to hfs_setattr() except it manipulates a file\n" + "that is already open.\n" + "\n" + "If an error occurs, this routine returns -1. Otherwise it returns 0."; + static PyObject *wrap_fsetattr(PyObject *self, PyObject *args) { hfsfile *arg_file; PyObject *arg_file_c; hfsdirent *arg_ent; Py_ssize_t arg_ent_len; @@ -400,6 +765,17 @@ static PyObject *wrap_fsetattr(PyObject *self, PyObject *args) return Py_None; } +static const char doc_mkdir[] = + "int hfs_mkdir(hfsvol *vol, const char *path);\n" + "\n" + "This routine creates a new, empty directory with the given path.\n" + "All parent directories must already exist, but there must not already\n" + "be a file or directory with the complete given path.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_mkdir(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -413,6 +789,16 @@ static PyObject *wrap_mkdir(PyObject *self, PyObject *args) return Py_None; } +static const char doc_rmdir[] = + "int hfs_rmdir(hfsvol *vol, const char *path);\n" + "\n" + "This routine deletes the directory with the given path. The directory\n" + "must be empty.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_rmdir(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -426,6 +812,15 @@ static PyObject *wrap_rmdir(PyObject *self, PyObject *args) return Py_None; } +static const char doc_delete[] = + "int hfs_delete(hfsvol *vol, const char *path);\n" + "\n" + "This routine deletes both forks of the file with the given path.\n" + "\n" + "The given `path' is assumed to be encoded using MacOS Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_delete(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_path; @@ -439,6 +834,24 @@ static PyObject *wrap_delete(PyObject *self, PyObject *args) return Py_None; } +static const char doc_rename[] = + "int hfs_rename(hfsvol *vol, const char *srcpath, const char *dstpath);\n" + "\n" + "This routine moves and/or renames the given `srcpath' to `dstpath'.\n" + "The source must exist; the destination must not exist, unless it is a\n" + "directory, in which case an attempt will be made to move the source\n" + "into the destination directory without changing its name.\n" + "\n" + "If both `srcpath' and `dstpath' refer to root directories, the volume\n" + "specified by `srcpath' will be renamed. Note that volume names may\n" + "only have 1-27 (HFS_MAX_VLEN) characters, while all other names may\n" + "have 1-31 (HFS_MAX_FLEN) characters.\n" + "\n" + "The given `srcpath' and `dstpath' are assumed to be encoded using MacOS\n" + "Standard Roman.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_rename(PyObject *self, PyObject *args) { hfsvol *arg_vol; PyObject *arg_vol_c; char *arg_srcpath; char *arg_dstpath; @@ -452,6 +865,33 @@ static PyObject *wrap_rename(PyObject *self, PyObject *args) return Py_None; } +static const char doc_zero[] = + "int hfs_zero(const char *path, unsigned int maxparts,\n" + " unsigned long *blocks);\n" + "\n" + "This routine initializes a medium with a new, empty driver descriptor\n" + "record and partition map. This is only necessary if it is desired to\n" + "partition the medium; the medium can be used as a whole without\n" + "partitions by specifying 0 to the routines which require a partition\n" + "number.\n" + "\n" + "The partition map will be empty, with the exception of an entry for the\n" + "partition map itself, plus an entry for the rest of the medium as free\n" + "space. To be useful, one or more HFS partitions should be created with\n" + "hfs_mkpart().\n" + "\n" + "The partition map will be created just large enough to allow `maxparts'\n" + "individual partitions to be created, not counting the partitions created\n" + "automatically by this routine. This number should be conservative, as\n" + "it may be impossible to create more than this many partitions for the\n" + "lifetime of the medium without re-initializing.\n" + "\n" + "If `blocks' is not NULL, the total number of blocks available for\n" + "partitioning (after the partition map structures have been created) will\n" + "be stored at this location.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_zero(PyObject *self, PyObject *args) { char *arg_path; unsigned int arg_maxparts; @@ -463,6 +903,21 @@ static PyObject *wrap_zero(PyObject *self, PyObject *args) return Py_BuildValue("k", ret_blocks); } +static const char doc_mkpart[] = + "int hfs_mkpart(const char *path, unsigned long len);\n" + "\n" + "This routine creates a new HFS partition having `len' blocks on the\n" + "given medium. Space for the partition will be taken from the available\n" + "free space as indicated in the existing partition map.\n" + "\n" + "It may not be possible to create the requested partition if there are\n" + "not enough free contiguous blocks on the medium, or if there is only\n" + "one slot left in the partition map and the request does not specify\n" + "all the remaining blocks in the free space. (The partition map cannot\n" + "leave any blocks in the medium unaccounted for.)\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_mkpart(PyObject *self, PyObject *args) { char *arg_path; unsigned long arg_len; @@ -473,6 +928,22 @@ static PyObject *wrap_mkpart(PyObject *self, PyObject *args) return Py_None; } +static const char doc_nparts[] = + "int hfs_nparts(const char *path);\n" + "\n" + "This routine determines the number of HFS partitions present on the\n" + "given medium, if any. If the medium specified by `path' is not\n" + "partitioned, -1 will be returned. Otherwise, a number denoting the total\n" + "number of HFS partitions is returned, including (possibly) 0.\n" + "\n" + "The number returned by this routine can help determine if a particular\n" + "medium is partitioned, and if so, the allowable range of partition\n" + "numbers which can be passed to the routines which require one. However,\n" + "passing 0 as a partition number always refers to the entire medium,\n" + "ignoring all partitions.\n" + "\n" + "If an error occurs, this function returns -1."; + static PyObject *wrap_nparts(PyObject *self, PyObject *args) { char *arg_path; @@ -485,6 +956,46 @@ static PyObject *wrap_nparts(PyObject *self, PyObject *args) return Py_BuildValue("i", ret); } +static const char doc_format[] = + "int hfs_format(const char *path, int pnum, int mode, const char *vname,\n" + " int nbadblocks, const unsigned long badblocks[]);\n" + "\n" + "This routine writes a new HFS file system to the specified `path', which\n" + "should be a block device or a writable file. The size of the volume is\n" + "determined either by the maximum size of the device or size of the file,\n" + "or by the size of the indicated partition within the medium.\n" + "\n" + "If `pnum' is > 0, it selects an ordinal HFS partition in the device\n" + "to receive the file system. The partition must already exist; an error\n" + "will result if it cannot be found. With `pnum' == 0, any partition\n" + "structure on the existing medium will be ignored, and the entire\n" + "device will be used for the new HFS volume.\n" + "\n" + "Volume options may be specified in the `mode' argument. In addition to\n" + "the options accepted by hfs_mount(), HFS_OPT_2048 may be specified to\n" + "request that the volume allocation blocks be aligned on physical\n" + "2048-byte block boundaries. Such a constraint is necessary to support\n" + "some hybrid CD-ROM file system formats, but is otherwise unnecessary and\n" + "may result in fewer allocation blocks altogether.\n" + "\n" + "The volume is given the name `vname', which must be between 1 and\n" + "HFS_MAX_VLEN (27) characters in length inclusively, and cannot contain\n" + "any colons (':'). This string is assumed to be encoded using MacOS\n" + "Standard Roman.\n" + "\n" + "It is possible to map out or \"spare\" bad blocks on the device such that\n" + "the file system will be made aware of these blocks and will not attempt\n" + "to use them to store data. To perform this magic, hfs_format() may be\n" + "passed an array of block numbers to spare. These numbers must\n" + "correspond to logical 512-byte blocks on the device and should be\n" + "relative to the beginning of the volume's partition, if any. If no\n" + "blocks need to be spared, 0 should be passed for `nbadblocks', and\n" + "`badblocks' may be a NULL pointer. Note that an error can occur if a\n" + "bad block occurs in a critical disk structure, or if there are too\n" + "many bad blocks (more than 25%) in the volume.\n" + "\n" + "If an error occurs, this function returns -1. Otherwise it returns 0."; + static PyObject *wrap_format(PyObject *self, PyObject *args) // bad blocks unimplemented { char *arg_path; int arg_pnum; int arg_mode; char *arg_vname; @@ -498,47 +1009,47 @@ static PyObject *wrap_format(PyObject *self, PyObject *args) // bad blocks unimp static PyMethodDef module_methods[] = { // Volume routines - {"mount", wrap_mount, METH_VARARGS, ""}, - {"flush", wrap_flush, METH_VARARGS, ""}, - {"flushall", wrap_flushall, METH_NOARGS, ""}, - {"umount", wrap_umount, METH_VARARGS, ""}, - {"umountall", wrap_umountall, METH_NOARGS, ""}, - {"getvol", wrap_getvol, METH_VARARGS, ""}, - {"setvol", wrap_setvol, METH_VARARGS, ""}, - {"vstat", wrap_vstat, METH_VARARGS, ""}, - {"vsetattr", wrap_vsetattr, METH_VARARGS, ""}, + {"mount", wrap_mount, METH_VARARGS, doc_mount}, + {"flush", wrap_flush, METH_VARARGS, doc_flush}, + {"flushall", wrap_flushall, METH_NOARGS, doc_flushall}, + {"umount", wrap_umount, METH_VARARGS, doc_umount}, + {"umountall", wrap_umountall, METH_NOARGS, doc_umountall}, + {"getvol", wrap_getvol, METH_VARARGS, doc_getvol}, + {"setvol", wrap_setvol, METH_VARARGS, doc_setvol}, + {"vstat", wrap_vstat, METH_VARARGS, doc_vstat}, + {"vsetattr", wrap_vsetattr, METH_VARARGS, doc_vsetattr}, // Directory routines - {"chdir", wrap_chdir, METH_VARARGS, ""}, - {"getcwd", wrap_getcwd, METH_VARARGS, ""}, - {"setcwd", wrap_setcwd, METH_VARARGS, ""}, - {"dirinfo", wrap_dirinfo, METH_VARARGS, ""}, - {"opendir", wrap_opendir, METH_VARARGS, ""}, - {"readdir", wrap_readdir, METH_VARARGS, ""}, - {"closedir", wrap_closedir, METH_VARARGS, ""}, + {"chdir", wrap_chdir, METH_VARARGS, doc_chdir}, + {"getcwd", wrap_getcwd, METH_VARARGS, doc_getcwd}, + {"setcwd", wrap_setcwd, METH_VARARGS, doc_setcwd}, + {"dirinfo", wrap_dirinfo, METH_VARARGS, doc_dirinfo}, + {"opendir", wrap_opendir, METH_VARARGS, doc_opendir}, + {"readdir", wrap_readdir, METH_VARARGS, doc_readdir}, + {"closedir", wrap_closedir, METH_VARARGS, doc_closedir}, // File routines - {"create", wrap_create, METH_VARARGS, ""}, - {"open", wrap_open, METH_VARARGS, ""}, - {"setfork", wrap_setfork, METH_VARARGS, ""}, - {"getfork", wrap_getfork, METH_VARARGS, ""}, - {"read", wrap_read, METH_VARARGS, ""}, - {"write", wrap_write, METH_VARARGS, ""}, - {"truncate", wrap_truncate, METH_VARARGS, ""}, - {"seek", wrap_seek, METH_VARARGS, ""}, - {"close", wrap_close, METH_VARARGS, ""}, + {"create", wrap_create, METH_VARARGS, doc_create}, + {"open", wrap_open, METH_VARARGS, doc_open}, + {"setfork", wrap_setfork, METH_VARARGS, doc_setfork}, + {"getfork", wrap_getfork, METH_VARARGS, doc_getfork}, + {"read", wrap_read, METH_VARARGS, doc_read}, + {"write", wrap_write, METH_VARARGS, doc_write}, + {"truncate", wrap_truncate, METH_VARARGS, doc_truncate}, + {"seek", wrap_seek, METH_VARARGS, doc_seek}, + {"close", wrap_close, METH_VARARGS, doc_close}, // Catalog routines - {"stat", wrap_stat, METH_VARARGS, ""}, - {"fstat", wrap_fstat, METH_VARARGS, ""}, - {"setattr", wrap_setattr, METH_VARARGS, ""}, - {"fsetattr", wrap_fsetattr, METH_VARARGS, ""}, - {"mkdir", wrap_mkdir, METH_VARARGS, ""}, - {"rmdir", wrap_rmdir, METH_VARARGS, ""}, - {"delete", wrap_delete, METH_VARARGS, ""}, - {"rename", wrap_rename, METH_VARARGS, ""}, + {"stat", wrap_stat, METH_VARARGS, doc_stat}, + {"fstat", wrap_fstat, METH_VARARGS, doc_fstat}, + {"setattr", wrap_setattr, METH_VARARGS, doc_setattr}, + {"fsetattr", wrap_fsetattr, METH_VARARGS, doc_fsetattr}, + {"mkdir", wrap_mkdir, METH_VARARGS, doc_mkdir}, + {"rmdir", wrap_rmdir, METH_VARARGS, doc_rmdir}, + {"delete", wrap_delete, METH_VARARGS, doc_delete}, + {"rename", wrap_rename, METH_VARARGS, doc_rename}, // Media routines - {"zero", wrap_zero, METH_VARARGS, ""}, - {"mkpart", wrap_mkpart, METH_VARARGS, ""}, - {"nparts", wrap_nparts, METH_VARARGS, ""}, - {"format", wrap_format, METH_VARARGS, ""}, + {"zero", wrap_zero, METH_VARARGS, doc_zero}, + {"mkpart", wrap_mkpart, METH_VARARGS, doc_mkpart}, + {"nparts", wrap_nparts, METH_VARARGS, doc_nparts}, + {"format", wrap_format, METH_VARARGS, doc_format}, {NULL, NULL, 0, NULL} };