home | help 
Tclzipfs(3)		     Tcl Library Procedures		     Tclzipfs(3)

________________________________________________________________________________

NAME
     TclZipfs_AppHook,	TclZipfs_Mount, TclZipfs_MountBuffer, TclZipfs_Unmount -
     handle ZIP files as Tcl virtual filesystems

SYNOPSIS
     const char *
     TclZipfs_AppHook(argcPtr, argvPtr)

     int
     TclZipfs_Mount(interp, zipname, mountpoint, password)

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

     int
     TclZipfs_Unmount(interp, mountpoint)

ARGUMENTS
     int *argcPtr (in)			  Pointer to a variable holding the num-
					  ber of  command  line  arguments  from
					  main().

     char ***argvPtr (in)		  Pointer  to  an  array of strings con-
					  taining the command line arguments  to
					  main().

     Tcl_Interp *interp (in)		  Interpreter in which the ZIP file sys-
					  tem is mounted.  The interpreter's re-
					  sult 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.

     const void *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 du-
					  ration of the mount.
________________________________________________________________________________

DESCRIPTION
     TclZipfs_AppHook is a utility function to perform standard application ini-
     tialization  procedures, taking into account available ZIP archives as fol-
     lows:

     [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  (VFS).  The value of ZIPFS_VOLUME can be retrieved using the
	    Tcl command zipfs root.

     [2]    If a file named main.tcl is located in the root  directory	of  that
	    file  system  (i.e.,  at  ZIPFS_VOLUME/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  ZIPFS_VOLUME/app/tcl_library/init.tcl is present, the
	    tcl_library global variable in the initial Tcl interpreter is set to
	    ZIPFS_VOLUME/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 di-
	    rectory or in the standard Tcl install location. (For  example,  the
	    Tcl 9.0.2 release would be searched for in a file libtcl_9_0_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 the application to  be
     compiled with the UNICODE preprocessor symbol defined (e.g., via the -DUNI-
     CODE compiler flag).

     The  result of TclZipfs_AppHook is the full Tcl version with build informa-
     tion (e.g., 9.0.0+abcdef...abcdef.gcc-1002).  The function may  modify  the
     variables	pointed  to by argcPtr and argvPtr to remove arguments; the cur-
     rent implementation does not do so, but callers should not assume that this
     will be true in the future.

     TclZipfs_Mount is used to mount ZIP archives and  to  retrieve  information
     about currently mounted archives. If mountpoint and zipname are both speci-
     fied  (i.e.  non-NULL),  the function mounts the ZIP archive zipname on the
     mount point given in mountpoint. If password is not NULL, it  should  point
     to  the  NUL  terminated  password protecting the archive. If not under the
     zipfs file system root, mountpoint is normalized with respect to  it.   For
     example,  a  mount  point passed as either mt or /mt would be normalized to
     //zipfs:/mt,  given  that	ZIPFS_VOLUME  as  returned  by	zipfs  root   is
     "//zipfs:/".  An error is raised if the mount point includes a drive or UNC
     volume.  On  success,  interp's result is set to the normalized mount point
     path.

     If mountpoint is a NULL pointer, information on all currently  mounted  ZIP
     file systems is stored in interp's result as a sequence of mount points and
     ZIP file names.

     If  mountpoint  is  not  NULL  but zipfile is NULL, the path to the archive
     mounted at that mount point is stored as interp's result. The function  re-
     turns a standard Tcl result code.

     TclZipfs_MountBuffer mounts the ZIP archive content data on the mount point
     given  in	mountpoint.  Both  mountpoint and data must be specified as non-
     NULL. The copy argument determines whether the buffer is internally  copied
     before  mounting or not. The ZIP archive is assumed to be not password pro-
     tected. On success, interp's result is set to the	normalized  mount  point
     path.

     TclZipfs_Unmount undoes the effect of TclZipfs_Mount, i.e., it unmounts the
     mounted  ZIP file system that was mounted from zipname (at mountpoint). Er-
     rors 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(n)

KEYWORDS
     compress, filesystem, zip

Tcl				       9.0			     Tclzipfs(3)
home | help