plucky (3) zzip_open_shared_io.3.gz

NAME

       zzip_open, zzip_open_ext_io, zzip_open_shared_io -  start usage.

SYNOPSIS

       #include <zzip/lib.h>

       ZZIP_FILE *
       zzip_open(zzip_char_t * filename, int o_flags)

       ZZIP_FILE *
       zzip_open_ext_io(zzip_char_t * filename, int o_flags, int o_modes,
                        zzip_strings_t * ext, zzip_plugin_io_t io)

       ZZIP_FILE *
       zzip_open_shared_io(ZZIP_FILE * stream,
                           zzip_char_t * filename, int o_flags, int o_modes,
                           zzip_strings_t * ext, zzip_plugin_io_t io)

DESCRIPTION

        The zzip_open function will open(2) a real/zipped file

        It has some magic functionality builtin - it will first try to open the given
       <emphasis>filename</emphasis> as a normal file. If it does not exist, the given path to the filename (if
       any) is split into its directory-part and the file-part. A ".zip" extension is then added to the
       directory-part to create the name of a zip-archive. That zip-archive (if it exists) is being searched for
       the file-part, and if found a zzip-handle is returned.

        Note that if the file is found in the normal fs-directory the returned structure is mostly empty and the
       zzip_read call will use the libc read(2) to obtain data. Otherwise a zzip_file_open is performed and any
       error mapped to errno(3).

        There was a possibility to transfer zziplib-specific openmodes through o_flags but you should please not
       use them anymore and look into zzip_open_ext_io to submit them down. The zzip_open function is shallow in
       that it just extracts the zzipflags and calls

        zzip_open_ext_io(filename, o_flags, zzipflags|0664, 0, 0)

        you must stop using this extra functionality (not well known anyway) since zzip_open might be later
       usable to open files for writing in which case the _EXTRAFLAGS will get in conflict.

        compare with open(2) and zzip_fopen

        The zzip_open_ext_io function uses explicit ext and io instead of the internal defaults, setting them to
       zero is equivalent to zzip_open

        note that the two flag types have been split into an o_flags (for fcntl-like openflags) and o_modes
       where the latter shall carry the zzip_flags and possibly accessmodes for unix filesystems. Since this
       version of zziplib can not write zipfiles, it is not yet used for anything else than zzip-specific
       modeflags.

        The zzip_open_ext_io function returns a new zzip-handle (use zzip_close to return it). On error the
       zzip_open_ext_io function will return null setting errno(3).

        If any ext_io handlers were used then the referenced structure should be static as the allocated
       ZZIP_FILE does not copy them.

        The zzip_open_shared_io function takes an extra stream argument - if a handle has been then ext/io can
       be left null and the new stream handle will pick up the ext/io. This should be used only in specific
       environment however since zzip_file_real does not store any ext-sequence.

        The benefit for the zzip_open_shared_io function comes in when the old file handle was openened from a
       file within a zip archive. When the new file is in the same zip archive then the internal zzip_dir
       structures will be shared. It is even quicker, as no check needs to be done anymore trying to guess the
       zip archive place in the filesystem, here we just check whether the zip archive's filepath is a prefix
       part of the filename to be opened.

        Note that the zzip_open_shared_io function is also used by zzip_freopen that will unshare the old
       handle, thereby possibly closing the handle.

        The zzip_open_shared_io function returns a new zzip-handle (use zzip_close to return it). On error the
       zzip_open_shared_io function will return null setting errno(3).

AUTHOR

        Guido Draheim <guidod@gmx.de> Tomi Ollila <Tomi.Ollila@iki.fi>

COPYRIGHT

        Copyright (c) Guido Draheim, use under copyleft (LGPL,MPL)