NAME¶

TclZipfs_AppHook, Tclzipfs_Mount, TclZipfs_MountBuffer, Tclzipfs_Unmount - handle ZIP files as Tcl virtual filesystems

SYNOPSIS¶

int
TclZipfs_AppHook(argcPtr, argvPtr)

int
Tclzipfs_Mount(interp, mountpoint, zipname, password)

int
TclZipfs_MountBuffer(interp, mountpoint, data, dataLen, copy)

int
Tclzipfs_Unmount(interp, mountpoint)

ARGUMENTS¶

int *argcPtr (in)

Pointer to a variable holding the number of command line arguments from main().

char ***argvPtr (in)

Pointer to an array of strings containing the command line arguments to main().

Tcl_Interp *interp (in)

Interpreter in which the ZIP file system is mounted. The interpreter's result is modified to hold the result or error message from the script.

const char *zipname (in)

Name of a ZIP file. Must not be NULL when either mounting or unmounting a ZIP.

const char *mountpoint (in)

Name of a mount point, which must be a legal Tcl file or directory name. May be NULL to query current mount points.

const char *password (in)

An (optional) password. Use NULL if no password is wanted to read the file.

unsigned char *data (in)

A data buffer to mount. The data buffer must hold the contents of a ZIP archive, and must not be NULL.

size_t dataLen (in)

The number of bytes in the supplied data buffer argument, data.

int copy (in)

If non-zero, the ZIP archive in the data buffer will be internally copied before mounting, allowing the data buffer to be disposed once TclZipfs_MountBuffer returns. If zero, the caller guarantees that the buffer will be valid to read from for the duration of the mount.

DESCRIPTION¶

TclZipfs_AppHook is a utility function to perform standard application initialization procedures, taking into account available ZIP archives as follows:

[1]

If the current application has a mountable ZIP archive, that archive is mounted under ZIPFS_VOLUME/app as a read-only Tcl virtual file system. ZIPFS_VOLUME is usually //zipfs: on all platforms, but zipfs: may also be used on Windows (due to differences in the platform's filename parsing).

[2]

If a file named main.tcl is located in the root directory of that file system (i.e., at ZIPROOT/app/main.tcl after the ZIP archive is mounted as described above) it is treated as the startup script for the process.

[3]

If the file ZIPROOT/app/tcl_library/init.tcl is present, the tcl_library global variable in the initial Tcl interpreter is set to ZIPROOT/app/tcl_library.

[4]

If the directory tcl_library was not found in the main application mount, the system will then search for it as either a VFS attached to the application dynamic library, or as a zip archive named libtcl_major_minor_patchlevel.zip either in the present working directory or in the standard Tcl install location. (For example, the Tcl 8.7.2 release would be searched for in a file libtcl_8_7_2.zip.) That archive, if located, is also mounted read-only.

On Windows, TclZipfs_AppHook has a slightly different signature, since it uses WCHAR instead of char. As a result, it requires your application to be compiled with the UNICODE preprocessor symbol defined (e.g., via the -DUNICODE compiler flag).

The result of TclZipfs_AppHook is a Tcl result code (e.g., TCL_OK when the function is successful). The function may modify the variables pointed to by argcPtr and argvPtr to remove arguments; the current implementation does not do so, but callers should not assume that this will be true in the future.

Tclzipfs_Mount mounts the ZIP archive zipname on the mount point given in mountpoint using the optional ZIP password password. Errors during that process are reported in the interpreter interp. If mountpoint is a NULL pointer, information on all currently mounted ZIP file systems is written into interp's result as a sequence of mount points and ZIP file names. The result of this call is a standard Tcl result code.

Tclzipfs_MountBuffer mounts the ZIP archive in the buffer pointed to by data on the mount point given in mountpoint. The ZIP archive is assumed to be not password protected. Errors during that process are reported in the interpreter interp. The copy argument determines whether the buffer is internally copied before mounting or not. The result of this call is a standard Tcl result code.

Tclzipfs_Unmount undoes the effect of Tclzipfs_Mount, i.e., it unmounts the mounted ZIP file system that was mounted from zipname (at mountpoint). Errors are reported in the interpreter interp. The result of this call is a standard Tcl result code.

TclZipfs_AppHook can not be used in stub-enabled extensions.

SEE ALSO¶

zipfs(3tcl)

KEYWORDS¶

compress, filesystem, zip