libzip API.md

NAME

libzip — library for manipulating zip archives

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>

DESCRIPTION

libzip is a library for reading, creating, and modifying zip archives.The main design criteria for libzip were:

  • Do not create corrupt files, even in case of errors.
  • Do not delete data.
  • Be efficient.

For this reason, when modifying zip archives, libzip writes to a temporary file and replaces the original zip archive atomically.Below there are two sections listing functions: one for how to read from zip archives and one for how to create/modify them.

READING ZIP ARCHIVES

open archive

zip_open(3),zip_fdopen(3)

find files

zip_name_locate(3)

read files

zip_fopen(3), zip_fopen_encrypted(3), zip_fopen_index(3), zip_fopen_index_encrypted(3), zip_fread(3), zip_fclose(3)

close archive

zip_close(3), zip_discard(3)

miscellaneous

zip_stat(3) , zip_file_get_comment(3), zip_get_archive_comment(3), zip_get_archive_flag(3), zip_get_name(3), zip_get_num_entries(3), zip_set_default_password(3)

CREATING/MODIFYING ZIP ARCHIVES

create/open archive

zip_open(3)

add/change files and directories

zip_dir_add(3), zip_file_add(3), zip_file_replace(3), zip_file_set_comment(3), zip_set_file_compression(3), zip_source_buffer(3), zip_source_file(3), zip_source_filep(3), zip_source_free(3), zip_source_function(3), zip_source_zip(3)

rename files

zip_rename(3)

delete files

zip_delete(3)

revert changes

zip_unchange(3), zip_unchange_all(3), zip_unchange_archive(3)

read/modify extra fields

zip_file_extra_field_by_id(3), zip_file_extra_field_delete(3), zip_file_extra_field_delete_by_id(3), zip_file_extra_field_get(3) ,zip_file_extra_field_set(3), zip_file_extra_fields_count(3) ,zip_file_extra_fields_count_by_id(3)

close archive

zip_close(3)

miscellaneous

zip_set_archive_comment(3) zip_set_archive_flag(3) zip_source(3)

ERROR HANDLING

zip_error_to_str(3) zip_strerror(3) zip_file_strerror(3) zip_error_get(3) zip_error_get_sys_type(3) zip_errors(3)


zip_open(3)


NAME

zip_open, zip_open_from_source — open zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_open(_const char *path_, _int flags_, _int *errorp_);_zip_t *_
zip_open_from_source(_zip_source_t *zs_, _int flags_, _zip_error_t *ze_);

DESCRIPTION

The zip_open() function opens the zip archive specified by path and returns a pointer to a struct zip, used to manipulate the archive. The flags are specified by or'ing the following values, or 0 for none of them.

  • ZIP_CHECKCONS
    Perform additional stricter consistency checks on the archive, and error if they fail.
  • ZIP_CREATE
    Create the archive if it does not exist.
  • ZIP_EXCL
    Error if archive already exists.
  • ZIP_TRUNCATE
    If archive exists, ignore its current contents. In other words, handle it the same way as an empty archive.
  • ZIP_RDONLY
    Open archive in read-only mode.

If an error occurs and errorp is non-NULL, it will be set to the corresponding error code.
The zip_open_from_source() function opens a zip archive encapsulated by the zip_source zs using the provided flags. In case of error, the zip_error ze is filled in.

RETURN VALUES

Upon successful completion zip_open() and zip_open_from_source() return a struct zip pointer. Otherwise, NULL is returned and zip_open() sets *errorp to indicate the error, while zip_open_from(source) sets ze to indicate the error.

ERRORS

The archive specified by path is opened unless:

  • [ZIP_ER_EXISTS]
    The file specified by path exists and ZIP_EXCL is set.
  • [ZIP_ER_INCONS]
    Inconsistencies were found in the file specified by path. This error is often caused by specifying ZIP_CHECKCONS but can also happen without it.
  • [ZIP_ER_INVAL]
    The path argument is NULL.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOENT]
    The file specified by path does not exist and ZIP_CREATE is not set.
  • [ZIP_ER_NOZIP]
    The file specified by path is not a zip archive.
  • [ZIP_ER_OPEN]
    The file specified by path could not be opened.
  • [ZIP_ER_READ]
    A read error occurred; see errno for details.
  • [ZIP_ER_SEEK]
    The file specified by path does not allow seeks.

SEE ALSO

libzip(3), zip_close(3), zip_error_to_str(3), zip_fdopen(3)


zip_fdopen(3)


NAME

zip_fdopen — open zip archive using open file descriptor

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_t *zip_fdopen(int fd, int flags, int *errorp);

DESCRIPTION

The zip archive specified by the open file descriptor fd is opened and a pointer to a struct zip, used to manipulate the archive, is returned. In contrast zip_open(3),sing zip_fdopen the archive can only be opened in read-only mode. The fd argument may not be used any longer after calling zip_fdopen. The flags are specified by or'ing the following values, or 0 for none of them.

  • ZIP_CHECKCONS
    Perform additional stricter consistency checks on the archive, and error if they fail.

If an error occurs and errorp is non-NULL, it will be set to the corresponding error code.

RETURN VALUES

Upon successful completion zip_fdopen() returns a struct zip pointer, and fd should not be used any longer, nor passed to close(2). Otherwise, NULL is returned and _*errorp_ is set to indicate the error. In the error case, fd remains unchanged.

ERRORS

The file specified by fd is prepared for use by libzip(3) unless:

  • [ZIP_ER_INCONS]
    Inconsistencies were found in the file specified by path. This error is often caused by specifying ZIP_CHECKCONS but can also happen without it.
  • [ZIP_ER_INVAL]
    The flags argument is invalid. Not all zip_open(3) flags are allowed for zip_fdopen, see DESCRIPTION.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOZIP]
    The file specified by fd is not a zip archive.
  • [ZIP_ER_OPEN]
    The file specified by fd could not be prepared for use by libzip(3).
  • [ZIP_ER_READ]
    A read error occurred; see errno for details.
  • [ZIP_ER_SEEK]
    The file specified by fd does not allow seeks.

SEE ALSO

libzip(3),zip_close(3), zip_error_to_str(3), zip_open(3)


zip_name_locate(3)


NAME

zip_name_locate — get index of file by name

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_name_locate(zip_t *archive, const char *fname, zip_flags_t flags);

DESCRIPTION

The zip_name_locate() function returns the index of the file named fname in archive. If archive does not contain a file with that name, -1 is returned. The flags are specified by or'ing the following values, or 0 for none of them.

  • ZIP_FL_NOCASE
    Ignore case distinctions. (Will only work well if the file names are ASCII.)
  • ZIP_FL_NODIR
    Ignore directory part of file name in archive.
  • ZIP_FL_ENC_RAW
    Compare against the unmodified names as it is in the ZIP archive.
  • ZIP_FL_ENC_GUESS
    (Default.) Guess the encoding of the name in the ZIP archive and convert it to UTF-8, if necessary, before comparing.
  • ZIP_FL_ENC_STRICT
    Follow the ZIP specification and expect CP-437 encoded names in the ZIP archive (except if they are explicitly marked as UTF-8). Convert it to UTF-8 before comparing.

Note: ASCII is a subset of both CP-437 and UTF-8.

RETURN VALUES

zip_name_locate() returns the index of the file named fname or -1, if archive does not contain an entry of that name.

ERRORS

zip_name_locate() fails if:

  • [ZIP_ER_NOENT]
    No entry of the name fname is found in the archive.
  • [ZIP_ER_INVAL]
    One of the arguments is invalid.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_get_name(3)


zip_fopen(3)

zip_fopen_index(3)


NAME

zip_fopen, zip_fopen_index — open file in zip archive for reading

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_file_t * zip_fopen(zip_t *archive, const char *fname, zip_flags_t flags);
zip_file_t * zip_fopen_index(zip_t *archive, zip_uint64_t index, zip_flags_t flags);

DESCRIPTION

The zip_fopen() function opens the file name fname in archive. The flags argument specifies how the name lookup should be done, according to the values are described in zip_name_locate(3). Also, the following values may be or'ed to it.

  • ZIP_FL_COMPRESSED
    Read the compressed data. Otherwise the data is uncompressed by zip_fread().
  • ZIP_FL_UNCHANGED
    Read the original data from the zip archive, ignoring any changes made to the file.

The zip_fopen_index() function opens the file at position index. If encrypted data is encountered, the functions call zip_fopen_encrypted(3) or zip_fopen_index_encrypted(3) respectively, using the default password set with zip_set_default_password(3).

RETURN VALUES

Upon successful completion, a struct zip_file pointer is returned. Otherwise, NULL is returned and the error code in archive is set to indicate the error.

ERRORS

  • ZIP_ER_CHANGED]
    The file data has been changed.
  • [ZIP_ER_COMPNOTSUPP]
    The compression method used is not supported.
  • [ZIP_ER_ENCRNOTSUPP]
    The encryption method used is not supported.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOPASSWD]
    The file is encrypted, but no password has been provided.
  • [ZIP_ER_READ]
    A file read error occurred.
  • [ZIP_ER_SEEK]
    A file seek error occurred.
  • [ZIP_ER_WRONGPASSWD]
    The provided password does not match the password used for encryption. Note that some incorrect passwords are not detected by the check done by zip_fopen().
  • [ZIP_ER_ZLIB]
    Initializing the zlib stream failed.

The function zip_fopen() may also fail and set zip_err for any of the errors specified for the routine zip_name_locate(3).

The function zip_fopen_index() may also fail with ZIP_ER_INVAL if index is invalid.

SEE ALSO

libzip(3), zip_fclose(3), zip_fread(3), zip_get_num_entries(3), zip_name_locate(3), zip_set_default_password(3)


zip_fopen_encrypted(3)

zip_fopen_index_encrypted(3)


NAME

zip_fopen_encrypted ,zip_fopen_index_encrypted — open encrypted file in zip archive for reading

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_file_t * zip_fopen_encrypted(zip_t *archive, const char *fname, zip_flags_t flags, const char *password);
zip_file_t * zip_fopen_index_encrypted(zip_t *archive, zip_uint64_t index, zip_flags_t flags, const char *password);

DESCRIPTION

The zip_fopen_encrypted() function opens the encrypted file name fname in archive using the password given in the password argument. The flags argument are the same as for zip_fopen(3).
The zip_fopen_index_encrypted() function opens the file at position index, see zip_fopen_index(3). These functions are called automatically by zip_fopen(3); you only need to call them if you want to specify a non-default password (see zip_set_default_password(3)).

RETURN VALUES

Upon successful completion, a struct zip_file pointer is returned. Otherwise, NULL is returned and the error code in archive is set to indicate the error.

ERRORS

  • [ZIP_ER_NOPASSWD]
    No password was provided.

The function zip_fopen_encrypted() may also fail and set zip_err for any of the errors specified for the routine zip_fopen(3).
The function zip_fopen_index_encrypted() may also fail and set zip_err for any of the errors specified for the routine zip_fopen_index(3).

SEE ALSO

libzip(3), zip_fclose(3), zip_fopen(3), zip_fread(3), zip_get_num_entries(3), zip_name_locate(3)


zip_fread(3)


NAME

zip_fread — read from file

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_fread(zip_file_t *file, void *buf, zip_uint64_t nbytes);

DESCRIPTION

The zip_fread() function reads at most nbytes bytes from file into buf.

RETURN VALUES

If successful, the number of bytes actually read is returned. Otherwise, -1 is returned.

SEE ALSO

libzip(3), zip_fclose(3), zip_fopen(3)


zip_fclose(3)


NAME

zip_fclose — close file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_fclose(zip_file_t *file);

DESCRIPTION

The zip_fclose() function closes file and frees the memory allocated for it.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, the error code is returned.

SEE ALSO

libzip(3), zip_fopen(3), zip_fread(3)


zip_close(3)


NAME

zip_close — close zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_close(zip_t *archive);

DESCRIPTION

The zip_close() function closes archive and frees the memory allocated for it. If any files within were changed, those changes are written to disk first. If writing changes fails, zip_close() fails and archive is left unchanged. If archive contains no files, the file is completely removed (no empty archive is written).

To close a zip file without saving changes, use zip_discard(3).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_close() will fail if:

  • [ZIP_ER_EOF]
    Unexpected end-of-file found while reading from a file.
  • [ZIP_ER_INTERNAL]
    The callback function of an added or replaced file returned an error but failed to report which.
  • [ZIP_ER_INVAL]
    The path argument is NULL.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOZIP]
    File is not a zip archive.
  • [ZIP_ER_READ]
    A file read failed.
  • [ZIP_ER_RENAME]
    A temporary file could not be renamed to its final name.
  • [ZIP_ER_SEEK]
    A file seek failed.
  • [ZIP_ER_TMPOPEN]
    A temporary file could not be created.
  • [ZIP_ER_WRITE]
    A file write failed.
  • [ZIP_ER_ZLIB]
    An error occurred while (de)compressing a stream with zlib(3).

Additionally, any errors returned by the callback function for added or replaced files will be passed back.
SEE ALSO
libzip(3), zip_discard(3), zip_error_get(3), zip_fdopen(3), zip_open(3), zip_strerror(3)


zip_discard(3)


NAME

zip_discard — close zip archive and discard changes

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
void zip_discard(zip_t *archive);

DESCRIPTION

The zip_discard() function closes archive and frees the memory allocated for it. Any changes to the archive are not written to disk and discarded.

SEE ALSO

libzip(3), zip_close(3)


zip_stat(3)

zip_stat_index(3)


NAME

zip_stat, zip_stat_index — get information about file

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_stat(zip_t *archive, const char *fname, zip_flags_t flags, zip_stat_t *sb);
int zip_stat_index(zip_t *archive, int index, zip_flags_t flags, zip_stat_t *sb);

DESCRIPTION

The zip_stat() function obtains information about the file named fname in archive. The flags argument specifies how the name lookup should be done. Its values are described in zip_name_locate(3). Also, ZIP_FL_UNCHANGED may be ored to it to request information about the original file in the archive, ignoring any changes made.
The zip_stat_index() function obtains information about the file at position index.
The sb argument is a pointer to a struct zip_stat (shown below), into which information about the file is placed.

struct zip_stat { 
zip_uint64_t valid; /* which fields have valid values */ 
const char *name; /* name of the file */ 
zip_uint64_t index; /* index within archive */ 
zip_uint64_t size; /* size of file (uncompressed) */ 
zip_uint64_t comp_size; /* size of file (compressed) */ 
time_t mtime; /* modification time */ 
zip_uint32_t crc; /* crc of file data */ 
zip_uint16_t comp_method; /* compression method used */ 
zip_uint16_t encryption_method; /* encryption method used */ 
zip_uint32_t flags; /* reserved for future use */ 
};

The structure pointed to by sb must be allocated before calling zip_stat() or zip_stat_index().
The valid field of the structure specifies which other fields are valid. Check if the flag defined by the following defines are in valid before accessing the fields:

  • ZIP_STAT_NAME
    name
  • ZIP_STAT_INDEX
    index
  • ZIP_STAT_SIZE
    size
  • ZIP_STAT_COMP_SIZE
    comp_size
  • ZIP_STAT_MTIME
    mtime
  • ZIP_STAT_CRC
    crc
  • ZIP_STAT_COMP_METHOD
    comp_method
  • ZIP_STAT_ENCRYPTION_METHOD
    encryption_method
  • ZIP_STAT_FLAGS
    flags

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error information in archive is set to indicate the error.

ERRORS

The function zip_stat() can fail for any of the errors specified for the routine zip_name_locate(3).

The function zip_stat_index() fails and sets the error information to ZIP_ER_INVAL if index is invalid. If ZIP_FL_UNCHANGED is not set and no information can be obtained from the source callback, the error information is set to ZIP_ER_CHANGED.

SEE ALSO

libzip(3), zip_get_num_entries(3), zip_name_locate(3), zip_stat_init(3)


zip_stat_init(3)


NAME

zip_stat_init — initialize zip_stat structure

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
void zip_stat_init(zip_stat_t *sb);

DESCRIPTION

The zip_stat_init() function initializes the members of a struct zip_stat. The current members are described in zip_stat(3), but this function should be used to initialize it to make sure none are missed. The structure pointed to by sb must be allocated before calling zip_stat_init().
This function should be used by functions provided to zip_source_function(3) when returning ZIP_SOURCE_STAT information to make sure all fields are initialized.

RETURN VALUES

If sb is valid, the function is always successful.

SEE ALSO

libzip(3), zip_stat(3)


zip_file_get_comment(3)


NAME

zip_file_get_comment — get comment for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
const char * zip_file_get_comment(zip_t *archive, zip_uint64_t index, zip_uint32_t *lenp, zip_flags_t flags);

DESCRIPTION

The zip_file_get_comment() function returns the comment for the file at position index in the zip archive. The name is in UTF-8 encoding unless ZIP_FL_ENC_RAW was specified (see below). This pointer should not be modified or free(3)'d, and becomes invalid when archive is closed. If lenp is not NULL, the integer to which it points will be set to the length of the comment. If flags is set to ZIP_FL_UNCHANGED, the original unchanged comment is returned.
Additionally, the following flags are supported:

  • ZIP_FL_ENC_RAW
    Return the unmodified comment as it is in the ZIP archive.
  • ZIP_FL_ENC_GUESS
    (Default.) Guess the encoding of the comment in the ZIP archive and convert it to UTF-8, if necessary.
  • ZIP_FL_ENC_STRICT
    Follow the ZIP specification for file names and extend it to file comments, expecting them to be encoded in CP-437 in the ZIP archive (except if it is a UTF-8 comment from the special extra field). Convert it to UTF-8.

Note: ASCII is a subset of both CP-437 and UTF-8.

RETURN VALUES

Upon successful completion, a pointer to the comment is returned, or NULL if there is no comment. In case of an error, NULL is returned and the error code in archive is set to indicate the error.

ERRORS

zip_file_get_comment() fails if:

  • [ZIP_ER_INVAL]
    index is not a valid file index in archive.

SEE ALSO

libzip(3), zip_file_set_comment(3), zip_get_archive_comment(3)


zip_get_archive_comment(3)


NAME

zip_get_archive_comment — get zip archive comment

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
const char * zip_get_archive_comment(zip_t *archive, int *lenp, zip_flags_t flags);

DESCRIPTION

The zip_get_archive_comment() function returns the comment for the entire zip archive. The name is in UTF-8 encoding unless ZIP_FL_ENC_RAW was specified (see below). This pointer should not be modified or free(3)'d, and becomes invalid when archive is closed. If lenp is not NULL, the integer to which it points will be set to the length of the comment. If flags is set to ZIP_FL_UNCHANGED, the original unchanged comment is returned.
Additionally, the following flags are supported:

  • ZIP_FL_ENC_RAW
    Return the unmodified archive comment as it is in the ZIP archive.
  • ZIP_FL_ENC_GUESS
    (Default.) Guess the encoding of the archive comment in the ZIP archive and convert it to UTF-8, if necessary.
  • ZIP_FL_ENC_STRICT
    Follow the ZIP specification for file names and extend it to the archive comment, thus also expecting it in CP-437 encoding. Convert it to UTF-8.

Note: ASCII is a subset of both CP-437 and UTF-8.

RETURN VALUES

Upon successful completion, a pointer to the comment is returned, or NULL if there is no comment.

SEE ALSO

libzip(3), zip_get_file_comment(3)


zip_get_archive_flag(3)


NAME

zip_get_archive_flag — get status flags for zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_get_archive_flag(zip_t *archive, zip_flags_t flag, zip_flags_t flags);

DESCRIPTION

The zip_get_archive_flag() function returns if the flag flag is set for the archive archive. The archive flags might have been changed with zip_set_archive_flag(); if flags is set to ZIP_FL_UNCHANGED, the original unchanged flags are tested.
Supported flags are:

  • ZIP_AFL_RDONLY
    The archive is read-only.

RETURN VALUES

zip_get_archive_flag() returns 1 if flag is set for archive, 0 if not, and -1 if an error occurred.
SEE ALSO

libzip(3), zip_set_archive_flag(3)


zip_get_name(3)


NAME

zip_get_name — get name of file by index

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
const char * zip_get_name(zip_t *archive, zip_uint64_t index, zip_flags_t flags);

DESCRIPTION

The zip_get_name() function returns the name of the file at position index in archive. The name is in UTF-8 encoding unless ZIP_FL_ENC_RAW was specified (see below).

If flags is set to ZIP_FL_UNCHANGED, the original unchanged filename is returned. The returned string must not be modified or freed, and becomes invalid when archive is closed.
Additionally, the following flags are supported:

  • ZIP_FL_ENC_RAW
    Return the unmodified names as it is in the ZIP archive.
  • ZIP_FL_ENC_GUESS
    (Default.) Guess the encoding of the name in the ZIP archive and convert it to UTF-8, if necessary.
  • ZIP_FL_ENC_STRICT
    Follow the ZIP specification and expect CP-437 encoded names in the ZIP archive (except if they are explicitly marked as UTF-8). Convert it to UTF-8.

Note: ASCII is a subset of both CP-437 and UTF-8.

RETURN VALUES

Upon successful completion, a pointer to the name is returned. Otherwise, NULL and the error code in archive is set to indicate the error.

ERRORS

zip_get_name() fails if:

  • [ZIP_ER_DELETED]
    index refers to a file that has been deleted (see zip_delete(3)).
  • [ZIP_ER_INVAL]
    index is not a valid file index in archive, or index points to an added file and ZIP_FL_UNCHANGED is set.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_name_locate(3)


zip_get_num_entries(3)


NAME

zip_get_num_entries — get number of files in archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_get_num_entries(zip_t *archive, zip_flags_t flags);

DESCRIPTION

The zip_get_num_entries() function returns the number of files in archive. If flags is set to ZIP_FL_UNCHANGED, the original number of entries is returned.
RETURN VALUES

zip_get_num_entries() returns the number of files in the zip archive, or -1 if archive is NULL.

SEE ALSO

libzip(3), zip_fopen_index(3), zip_stat_index(3)


zip_set_default_password(3)


NAME

zip_set_default_password — set default password for encrypted files in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_set_default_password(zip_t *archive, const char *password);

DESCRIPTION

The zip_set_default_password() function sets the default password used when accessing encrypted files. If password is NULL, the default password is unset.
If you prefer a different password for single files, use zip_fopen_encrypted(3) instead of zip_fopen(3). Usually, however, the same password is used for every file in an zip archive.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error information in archive is set to indicate the error.

ERRORS

zip_set_default_password() fails if:

  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_fopen(3), zip_fopen_encrypted(3)


zip_dir_add(3)


NAME

zip_dir_add — add directory to zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_dir_add(zip_t *archive, const char *name, zip_flags_t flags);

DESCRIPTION

The function zip_dir_add() adds a directory to a zip archive. The argument archive specifies the zip archive to which the directory should be added. name is the directory's name in the zip archive. The flags argument can be any of:

  • ZIP_FL_ENC_GUESS
    Guess encoding of name (default).
  • ZIP_FL_ENC_UTF_8
    Interpret name as UTF-8.
  • ZIP_FL_ENC_CP437
    Interpret name as code page 437 (CP-437).

RETURN VALUES

Upon successful completion, the index of the new entry in the archive is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_dir_add() fails if:

  • [ZIP_ER_EXISTS]
    There is already an entry called name in the archive.
  • [ZIP_ER_INVAL]
    archive or name are NULL, or invalid UTF-8 encoded file names.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_add(3)


zip_file_add(3)

zip_file_replace(3)

NAME

zip_file_add, zip_file_replace — add file to zip archive or replace file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_file_add(zip_t *archive, const char *name, zip_source_t *source, zip_flags_t flags);

int zip_file_replace(zip_t *archive, zip_uint64_t index, zip_source_t *source, zip_flags_t flags);

DESCRIPTION

The function zip_file_add() adds a file to a zip archive, while zip_file_replace() replaces an existing file in a zip archive. The argument archive specifies the zip archive to which the file should be added. name is the file's name in the zip archive (for zip_file_add()), while index specifies which file should be replaced (for zip_file_replace()). The flags argument can be any combination of zip_file_replace with one of ZIP_FL_ENC_*:

  • ZIP_FL_OVERWRITE
    Overwrite any existing file of the same name. For zip_file_add only.
  • ZIP_FL_ENC_GUESS
    Guess encoding of name (default).
  • ZIP_FL_ENC_UTF_8
    Interpret name as UTF-8.
  • ZIP_FL_ENC_CP437
    Interpret name as code page 437 (CP-437).

The data is obtained from the source argument, see zip_source(3).

RETURN VALUES

Upon successful completion, zip_file_add() returns the index of the new file in the archive, and zip_file_replace() returns 0. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

EXAMPLES

zip_source_t *s; 
const char buf="teststring"; 

if ((s=zip_source_buffer(archive, buffer, sizeof(buf), 0)) == NULL || 
zip_file_add(archive, name, s, ZIP_FL_ENC_UTF_8) < 0) { 
zip_source_free(s); 
printf("error adding file: %s\n", zip_strerror(archive)); 
}

ERRORS

zip_file_add() and zip_file_replace() fail if:

  • [ZIP_ER_EXISTS]
    There is already a file called name in the archive. (Only applies to zip_file_add(), and only if ZIP_FL_OVERWRITE is not provided).
  • [ZIP_ER_INVAL]
    source or name are NULL, or index is invalid.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_RDONLY]
    Archive was opened in read-only mode.

SEE ALSO

libzip(3), zip_source(3)


zip_file_set_comment(3)


NAME

zip_file_set_comment — set comment for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_set_file_comment(zip_t *archive, zip_uint64_t index, const char *comment, zip_uint16_t len, zip_flags_t flags);

DESCRIPTION

The zip_file_set_comment() function sets the comment for the file at position index in the zip archive to comment of length len. If comment is NULL and len is 0, the file comment will be removed. The flags argument can be any of:

  • ZIP_FL_ENC_GUESS
    Guess encoding of comment (default).
  • ZIP_FL_ENC_UTF_8
    Interpret comment as UTF-8.
  • ZIP_FL_ENC_CP437
    Interpret comment as code page 437 (CP-437).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error information in archive is set to indicate the error.

ERRORS

zip_file_set_comment() fails if:

  • [ZIP_ER_INVAL]
    index is not a valid file index in archive, or len is less than 0 or longer than the maximum comment length in a zip file (65535), or comment is not a valid UTF-8 encoded string.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_RDONLY]
    The archive was opened in read-only mode.

SEE ALSO

libzip(3), zip_file_get_comment(3), zip_get_archive_comment(3), zip_set_archive_comment(3)


zip_set_file_compression(3)


NAME

zip_set_file_compression — set compression method for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_set_file_compression(zip_t *archive, zip_uint64_t index, zip_int32_t comp, zip_uint32_t comp_flags);

DESCRIPTION

The zip_set_file_compression() function sets the compression method for the file at position index in the zip archive to comp with the compression method specific comp_flags. The comp is the same as returned by zip_stat(3). For the comp argument, currently only the following values are supported:

  • ZIP_CM_DEFAULT
    default compression; currently the same as ZIP_CM_DEFLATE.
  • ZIP_CM_STORE
    Store the file uncompressed.
  • ZIP_CM_DEFLATE
    Deflate the file with the zlib(3) algorithm and default options

The comp_flags argument is currently ignored.

The current compression method for a file in a zip archive can be determined using zip_stat(3).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error information in archive is set to indicate the error.

ERRORS

zip_set_file_compression() fails if:

  • [ZIP_ER_INVAL]
    index is not a valid file index in archive, or the argument combination is invalid.
  • [ZIP_ER_COMPNOTSUPP]
    Unsupported compression method requested.
  • [ZIP_ER_RDONLY]
    Read-only zip file, no changes allowed.

SEE ALSO

libzip(3), zip_stat(3)


zip_source_buffer(3)


NAME

zip_source_buffer — create zip data source from buffer

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_source_t * zip_source_buffer(zip_t *archive, const void *data, zip_uint64_t len, int freep);
zip_source_t * zip_source_buffer_create(const void *data, zip_uint64_t len, int freep, zip_error_t *error);

DESCRIPTION

The functions zip_source_buffer() and zip_source_buffer_create() create a zip source from the buffer data of size len. If freep is non-zero, the buffer will be freed when it is no longer needed. data must remain valid for the lifetime of the created source.
The source can be used to open a zip archive from.

RETURN VALUES

Upon successful completion, the created source is returned. Otherwise, NULL is returned and the error code in archive or error is set to indicate the error.

ERRORS

zip_source_buffer() and zip_source_buffer_create() fail if:

  • [ZIP_ER_INVAL]
    len is greater than zero and data is NULL.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_add(3), zip_open_from_source(3), zip_replace(3), zip_source(3)


zip_add(3)

zip_replace(3)


NAME

zip_add, zip_replace — add file to zip archive or replace file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int64_t zip_add(zip_t *archive, const char *name, zip_source_t *source);

int zip_replace(zip_t *archive, zip_uint64_t index, zip_source_t *source);

DESCRIPTION

The function zip_add() is the obsolete version of zip_file_add(3). It is the same as calling zip_file_add(3) with an empty flags argument. Similarly, the zip_replace() function is the obsolete version of zip_file_replace(3). It is the same as calling zip_file_replace(3) with an empty flags argument.

SEE ALSO

libzip(3), zip_file_add(3), zip_file_replace(3)


zip_source_file(3)


NAME

zip_source_file — create data source from a file

LIBRARY

libzip (-lzip)

SYNOPSIS

zip_source_t * zip_source_file(zip_t *archive, const char *fname, zip_uint64_t start, zip_int64_t len);
zip_source_t * zip_source_file_create(const char *fname, zip_uint64_t start, zip_int64_t len, zip_error_t *error);

DESCRIPTION

The functions zip_source_file() and zip_source_file_create() create a zip source from a file. They open fname and read len bytes from offset start from it. If len is 0 or -1, the whole file (starting from start) is used.
If the file supports seek, the source can be used to open a zip archive from.

The file is opened and read when the data from the source is used, usually by zip_close() or zip_open_from_source().

RETURN VALUES

Upon successful completion, the created source is returned. Otherwise, NULL is returned and the error code in archive or error is set to indicate the error.

ERRORS

zip_source_file() and zip_source_file_create() fail if:

  • [ZIP_ER_INVAL]
    fname, start, or len are invalid.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_OPEN]
    Opening fname failed.

SEE ALSO

libzip(3), zip_add(3), zip_replace(3), zip_source(3)


zip_source_filep(3)


NAME

zip_source_filep — create data source from FILE *

LIBRARY

libzip (-lzip)

SYNOPSIS

zip_source_t * zip_source_filep(zip_t *archive, FILE *file, zip_uint64_t start, zip_int64_t len);
zip_source_t * zip_source_filep(FILE *file, zip_uint64_t start, zip_int64_t len, zip_error_t *error);

DESCRIPTION

The functions zip_source_filep() and zip_source_filep_create() create a zip source from a file stream. They read len bytes from offset start from the open file stream file. If len is 0 or -1, the whole file (starting from start) is used.
If the file stream supports seeking, the source can be used to open a read-only zip archive from.
The file stream is closed when the source is being freed, usually by zip_close(3).

RETURN VALUES

Upon successful completion, the created source is returned. Otherwise, NULL is returned and the error code in archive or error is set to indicate the error.

ERRORS

zip_source_filep() fails if:

  • [ZIP_ER_INVAL]
    file, start, or len are invalid.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_add(3), zip_replace(3), zip_source(3)


zip_source_free(3)


NAME

zip_source_free — free zip data source

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
void zip_source_free(zip_source_t *source);

DESCRIPTION

The function zip_source_free() decrements the reference count of source and frees it if the reference count drops to 0. If source is NULL, it does nothing.
NOTE: This function should not be called on a source after it was used successfully in a zip_open_from_source(3), zip_add(3), or zip_replace(3) call.

SEE ALSO

libzip(3), zip_source(3), zip_source_keep(3)


zip_source_keep(3)


NAME

zip_source_keep — increment reference count of zip data source

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
void zip_source_keep(zip_source_t *source);

DESCRIPTION

The function zip_source_keep() increments the reference count of source.

SEE ALSO

libzip(3), zip_source(3), zip_source_free(3)


zip_source_function(3)


NAME

zip_source_function — create data source from function

LIBRARY

libzip (-lzip)

 SYNOPSIS

#include <zip.h>
zip_source_t * zip_source_function(zip_t *archive, zip_source_callback fn, void *userdata);
zip_source_t * zip_source_function_create(zip_source_callback fn, void *userdata, zip_error_t *error);

DESCRIPTION

The functions zip_source_function() and zip_source_function_create() creates a zip source from the user-provided function fn, which must be of the following type:
typedef zip_int64_t (zip_source_callback)(void userdata, void *data, zip_uint64_t len, zip_source_cmd_t cmd);
archive or error are used for reporting errors and can be NULL.
When called by the library, the first argument is the userdata argument supplied to the function. The next two arguments are a buffer data of size len when data is passed in or expected to be returned, or else NULL and 0. The last argument, cmd, specifies which action the function should perform.
Depending on the uses, there are three useful sets of commands to be supported by a zip_source_callback():

read source

Providing streamed data (for file data added to archives). Must support ZIP_SOURCE_OPEN, ZIP_SOURCE_READ, ZIP_SOURCE_CLOSE, ZIP_SOURCE_STAT, and ZIP_SOURCE_ERROR.

seekable read source

Same as previous, but from a source allowing reading from arbitrary offsets (also for read-only zip archive). Must additionally support ZIP_SOURCE_SEEK, ZIP_SOURCE_TELL, and ZIP_SOURCE_SUPPORTS.

read/write source

Same as previous, but additionally allowing writing (also for writable zip archives). Must additionally support ZIP_SOURCE_BEGIN_WRITE, ZIP_SOURCE_COMMIT_WRITE, ZIP_SOURCE_ROLLBACK_WRITE, ZIP_SOURCE_SEEK_WRITE, ZIP_SOURCE_TELL_WRITE, and ZIP_SOURCE_REMOVE.
ZIP_SOURCE_BEGIN_WRITE

Prepare the source for writing. Use this to create any temporary file(s).

ZIP_SOURCE_CLOSE

Reading is done.

ZIP_SOURCE_COMMIT_WRITE

Finish writing to the source. Replace the original data with the newly written data. Clean up temporary files or internal buffers. Subsequently opening and reading from the source should return the newly written data.

ZIP_SOURCE_ERROR

Get error information. data points to an array of two ints, which should be filled with the libzip error code and the corresponding system error code for the error that occurred. See zip_errors(3) for details on the error codes. If the source stores error information in a zip_error_t, use zip_error_to_data(3) and return its return value. Otherwise, return 2 * sizeof(int).

ZIP_SOURCE_FREE

Clean up and free all resources, including state. The callback function will not be called again.

ZIP_SOURCE_OPEN

Prepare for reading.

ZIP_SOURCE_READ

Read data into the buffer data of size len. Return the number of bytes placed into data on success.

ZIP_SOURCE_REMOVE

Remove the underlying file. This is called if a zip archive is empty when closed.

ZIP_SOURCE_ROLLBACK_WRITE

Abort writing to the source. Discard written data. Clean up temporary files or internal buffers. Subsequently opening and reading from the source should return the original data.

ZIP_SOURCE_SEEK

Specify position to read next byte from, like fseek(3). Use ZIP_SOURCE_GET_ARGS(3) to decode the arguments into the following struct:

struct zip_source_args_seek { 
zip_int64_t offset; 
int whence; 
};

If the size of the source's data is known, use zip_source_seek_compute_offset(3) to validate the arguments and compute the new offset.

ZIP_SOURCE_SEEK_WRITE

Specify position to write next byte to, like fseek(3). See ZIP_SOURCE_SEEK for details.

ZIP_SOURCE_STAT

Get meta information for the input data. data points to an allocated struct zip_stat, which should be initialized using zip_stat_init(3) and then filled in. Information only available after the source has been read (e.g. size) can be omitted in an earlier call. Return sizeof(struct zip_stat) on success. NOTE: zip_source_function() may be called with this argument even after being called with ZIP_SOURCE_CLOSE.

ZIP_SOURCE_SUPPORTS

Return bitmap specifying which commands are supported. Use zip_source_make_command_bitmap(3). If this command is not implemented, the source is assumed to be a read source without seek support.

ZIP_SOURCE_TELL

Return the current read offset in the source, like ftell(3).

ZIP_SOURCE_TELL_WRITE

Return the current write offset in the source, like ftell(3).

ZIP_SOURCE_WRITE

Write data to the source. Return number of bytes written.
Return Values

Commands should return -1 on error. ZIP_SOURCE_ERROR will be called to retrieve the error code. On success, commands return 0, unless specified otherwise in the description above.
Calling Conventions

The library will always issue ZIP_SOURCE_OPEN before issuing ZIP_SOURCE_READ, ZIP_SOURCE_SEEK, or ZIP_SOURCE_TELL. When it no longer wishes to read from this source, it will issue ZIP_SOURCE_CLOSE. If the library wishes to read the data again, it will issue ZIP_SOURCE_OPEN a second time. If the function is unable to provide the data again, it should return -1.
ZIP_SOURCE_BEGIN_WRITE will be called before ZIP_SOURCE_WRITE, ZIP_SOURCE_SEEK_WRITE, or ZIP_SOURCE_TELL_WRITE. When writing is complete, either ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE will be called.
ZIP_SOURCE_STAT can be issued at any time.
ZIP_SOURCE_ERROR will only be issued in response to the function returning -1.
ZIP_SOURCE_FREE will be the last command issued; if ZIP_SOURCE_OPEN was called and succeeded, ZIP_SOURCE_CLOSE will be called before ZIP_SOURCE_FREE, and similarly for ZIP_SOURCE_BEGIN_WRITE and ZIP_SOURCE_COMMIT_WRITE or ZIP_SOURCE_ROLLBACK_WRITE.

RETURN VALUES

Upon successful completion, the created source is returned. Otherwise, NULL is returned and the error code in archive or error is set to indicate the error (unless it is NULL).

ERRORS

zip_source_function() fails if:

[ZIP_ER_MEMORY]

Required memory could not be allocated.

SEE ALSO

libzip(3), zip_add(3), zip_replace(3), zip_source(3), zip_stat_init(3)


zip_source_zip(3)


NAME

zip_source_zip — create data source from zip file

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_source_t * zip_source_zip(zip_t *archive, zip_t *srcarchive, zip_uint64_t srcidx, zip_flags_t flags, zip_uint64_t start, zip_int64_t len);

DESCRIPTION

The function zip_source_zip() creates a zip source from a file in a zip archive. The srcarchive argument is the (open) zip archive containing the source zip file at index srcidx. len bytes from offset start will be used in the zip_source. If len is 0 or -1, the rest of the file, starting from start, is used. If start is zero and len is -1, the whole file will be copied without decompressing it.
Supported flags are:

  • ZIP_FL_UNCHANGED
    Try to get the original data without any changes that may have been made to srcarchive after opening it.
    ZIP_FL_RECOMPRESS
    When adding the data from srcarchive, re-compress it using the current settings instead of copying the compressed data.
    RETURN VALUES
    Upon successful completion, the created source is returned. Otherwise, NULL is returned and the error code in archive is set to indicate the error.

ERRORS

zip_source_zip() fails if:

  • [ZIP_ER_CHANGED]
    Unchanged data was requested, but it is not available.

  • [ZIP_ER_INVAL]
    srcarchive, srcidx, start, or len are invalid.

  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

Additionally, it can return all error codes from zip_stat_index() and zip_fopen_index().

SEE ALSO

libzip(3), zip_add(3), zip_replace(3), zip_source(3)


zip_rename(3)


NAME

zip_rename — rename file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_rename(zip_t *archive, zip_uint64_t index, const char *name);

DESCRIPTION

zip_rename() is the obsolete version of zip_file_rename(3). It is the same as calling zip_file_rename(3) with an empty flags argument.

SEE ALSO

libzip(3), zip_file_rename(3)


zip_file_rename(3)


NAME

zip_file_rename — rename file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_file_rename(zip_t *archive, zip_uint64_t index, const char *name, zip_flags_t flags);

DESCRIPTION

The file at position index in the zip archive archive is renamed to name. The flags argument can be any of:

  • ZIP_FL_ENC_GUESS
    Guess encoding of name (default).
  • ZIP_FL_ENC_UTF_8
    Interpret name as UTF-8.
  • ZIP_FL_ENC_CP437
    Interpret name as code page 437 (CP-437).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_rename() fails if:

  • [ZIP_ER_DELETED]
    The file to be renamed has been deleted from the archive.
  • [ZIP_ER_EXISTS]
    There is already a file called name in the archive.
  • [ZIP_ER_INVAL]
    index is not a valid file index in archive, name is NULL, the empty string, or not a valid UTF-8 encoded string. Also a file cannot be renamed to a directory or vice versa. Directories are denoted by a trailing slash.

SEE ALSO

libzip(3), zip_unchange(3)


zip_delete(3)


 NAME

zip_delete — delete file from zip archive

 LIBRARY

libzip (-lzip)

 SYNOPSIS

#include <zip.h>
int zip_delete(zip_t *archive, zip_uint64_t index);

DESCRIPTION

The file at position index in the zip archive archive is marked as deleted.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_delete() fails if:

  • [ZIP_ER_INVAL]
    index is not a valid file index in archive.

SEE ALSO

libzip(3), zip_unchange(3)


zip_unchange(3)


NAME

zip_unchange — undo changes to file in zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_unchange(zip_t *archive, int index);

DESCRIPTION

Changes to the file at position index are reverted.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_unchange() fails if:

  • [ZIP_ER_EXISTS]
    Unchanging the name would result in a duplicate name in the archive.
  • [ZIP_ER_INVAL]
    index is not a valid file index in zip.

SEE ALSO

libzip(3), zip_unchange_all(3), zip_unchange_archive(3)


zip_unchange_all(3)


NAME

zip_unchange_all — undo all changes in a zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_unchange_all(zip_t *archive);

DESCRIPTION

All changes to files and global information in archive are reverted.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

SEE ALSO

libzip(3), zip_unchange(3), zip_unchange_archive(3)


zip_unchange_archive(3)


NAME

zip_unchange_archive — undo global changes to zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_unchange_archive(zip_t *archive);

DESCRIPTION

Revert all global changes to the archive archive. This reverts changes to the archive comment and global flags.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

SEE ALSO

libzip(3), zip_unchange(3), zip_unchange_all(3)


zip_file_extra_field_by_id(3)


官网未给出


zip_file_extra_field_delete(3)

zip_file_extra_field_delete_by_id(3)


NAME

zip_file_extra_field_delete, zip_file_extra_field_delete_by_id — delete extra field for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_file_extra_field_delete(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_index, zip_flags_t flags);
int zip_file_extra_field_delete_by_id(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_id, zip_uint16_t extra_field_index, zip_flags_t flags);

DESCRIPTION

The zip_file_extra_field_delete() function deletes the extra field with index extra_field_index for the file at position index in the zip archive.
If*** extra_field_index*** is ZIP_EXTRA_FIELD_ALL, then all extra fields will be deleted.
The following flags are supported:

  • ZIP_FL_CENTRAL
    Delete extra fields from the archive's central directory.
  • ZIP_FL_LOCAL
    Delete extra fields from the local file headers.

The zip_file_extra_field_delete_by_id() function deletes the extra field with ID (two-byte signature) extra_field_id and index extra_field_index (in other words, the extra_field_index'th extra field with ID extra_field_id) The other arguments are the same as for zip_file_extra_field_delete() (ZIP_EXTRA_FIELD_ALL will delete all extra fields of the specified ID).
Please note that due to the library design, the index of an extra field may be different between central directory and local file headers. For this reason, it is not allowed to specify both ZIP_FL_CENTRAL and ZIP_FL_LOCAL in flags, except when deleting all extra fields (i.e., extra_field_index being ZIP_EXTRA_FIELD_ALL).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_file_extra_field_delete() and zip_file_extra_field_delete_by_id() fail if:

  • [ZIP_ER_NOENT]
    index is not a valid file index in archive.

SEE ALSO

libzip(3), zip_file_extra_field_get(3), zip_file_extra_field_set(3), zip_file_extra_fields_count(3)


zip_file_extra_field_get(3)

zip_file_extra_field_get_by_id(3)


NAME

zip_file_extra_field_get, zip_file_extra_field_get_by_id — get extra field for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
const zip_uint8_t * zip_file_extra_field_get(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_index, zip_uint16_t *idp, zip_uint16_t *lenp, zip_flags_t flags);
const zip_uint8_t * zip_file_extra_field_get_by_id(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_id, zip_uint16_t extra_field_index, zip_uint16_t *lenp, zip_flags_t flags);

DESCRIPTION

The zip_file_extra_field_get() function returns the extra field with index extra_field_index for the file at position index in the zip archive. This pointer should not be modified or free(3)'d, and becomes invalid when archive is closed. If idp is not NULL, the integer to which it points will be set to the ID (two-byte signature) of the selected extra field. If lenp is not NULL, the integer to which it points will be set to the length of the extra field. Generally speaking, lenp and idp should be passed since only the extra field data is returned (i.e., neither the ID nor the length, if the idp and lenp arguments are not provided).
The following flags are supported:

  • ZIP_FL_CENTRAL
    Return extra fields from the archive's central directory.
  • ZIP_FL_LOCAL
    Return extra fields from the local file headers.
  • ZIP_FL_UNCHANGED
    Return the original unchanged extra fields, ignoring any changes made.

The zip_file_extra_field_get_by_id() function returns the extra field with ID (two-byte signature) extra_field_id and index extra_field_index (in other words, the extra_field_index'th extra field with ID extra_field_id) The other arguments are the same as for zip_file_extra_field_get().

RETURN VALUES

Upon successful completion, a pointer to an extra field is returned, or NULL if there is no extra field with that extra_field_index for the file with index index. In case of an error, NULL is returned and the error code in archive is set to indicate the error.

ERRORS

zip_file_extra_field_get() and zip_file_extra_field_get_by_id() fail if:

  • [ZIP_ER_NOENT]
    index is not a valid file index in archive, or extra_field_index is not a valid extra file index (for ID extra_field_id).

SEE ALSO

libzip(3), zip_file_extra_field_delete(3), zip_file_extra_field_set(3), zip_file_extra_fields_count(3)


zip_file_extra_field_set(3)


NAME

zip_file_extra_field_set — set extra field for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_file_extra_field_set(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_id, zip_uint16_t extra_field_index, const zip_uint8_t *extra_field_data, zip_uint16_t len, zip_flags_t flags);

DESCRIPTION

The zip_file_extra_field_set() function sets the extra field with ID (two-byte signature) extra_field_id and index extra_field_index for the file at position index in the zip archive. The extra field's data will be set to extra_field_data and length len. If a new entry shall be appended, set extra_field_index to ZIP_EXTRA_FIELD_NEW.

At least one of the following flags must be set:

  • ZIP_FL_CENTRAL
    Set extra field in the archive's central directory.
  • ZIP_FL_LOCAL
    Set extra field in the local file headers.

Please note that the extra field IDs 0x0001 (ZIP64 extension), 0x6375 (Infozip UTF-8 comment), and 0x7075 (Infozip UTF-8 file name) can not be set using zip_file_extra_field_set() since they are set by libzip(3) automatically when needed.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_file_extra_field_set() fails if:

  • [ZIP_ER_INVAL]
    The extra field size is too large (ID and length need 4 bytes; the maximum length of all extra fields for one file combined is 65536 bytes). This error also occurs if extra_field_index is too large.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOENT]
    index is not a valid file index in archive.

SEE ALSO

libzip(3), zip_file_extra_field_delete(3), zip_file_extra_field_get(3), zip_file_extra_fields_count(3)


zip_file_extra_fields_count(3)

zip_file_extra_fields_count_by_id(3)


NAME

zip_file_extra_fields_count, zip_file_extra_fields_count_by_id — count extra fields for file in zip

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
zip_int16_t zip_file_extra_fields_count(zip_t *archive, zip_uint64_t index, zip_flags_t flags);
zip_int16_t zip_file_extra_fields_count_by_id(zip_t *archive, zip_uint64_t index, zip_uint16_t extra_field_id, zip_flags_t flags);

DESCRIPTION

The zip_file_extra_fields_count() function counts the extra fields for the file at position index in the zip archive.
The following flags are supported:

  • ZIP_FL_CENTRAL
    Count extra fields from the archive's central directory.
  • ZIP_FL_LOCAL
    Count extra fields from the local file headers.
  • ZIP_FL_UNCHANGED
    Count the original unchanged extra fields, ignoring any changes made.

The zip_file_extra_fields_count_by_id() function counts the extra fields with ID (two-byte signature) extra_field_id. The other arguments are the same as for zip_file_extra_fields_count().
Extra fields that are the same in the central directory and the local file header are merged into one. Therefore, the counts with ZIP_FL_CENTRAL and ZIP_FL_LOCAL do not need to add up to the same value as when given ZIP_FL_CENTRAL|ZIP_FL_LOCAL at the same time.

RETURN VALUES

Upon successful completion, the requested number of extra fields is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_file_extra_fields_count() and zip_file_extra_fields_count_by_id() fail if:

  • [ZIP_ER_NOENT]
    index is not a valid file index in archive.

SEE ALSO

libzip(3), zip_file_extra_field_delete(3), zip_file_extra_field_get(3), zip_file_extra_field_set(3)


zip_close(3)


NAME

zip_close — close zip archive

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_close(zip_t *archive);

DESCRIPTION

The zip_close() function closes archive and frees the memory allocated for it. If any files within were changed, those changes are written to disk first. If writing changes fails, zip_close() fails and archive is left unchanged. If archive contains no files, the file is completely removed (no empty archive is written).
To close a zip file without saving changes, use zip_discard(3).

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error code in archive is set to indicate the error.

ERRORS

zip_close() will fail if:

  • [ZIP_ER_EOF]
    Unexpected end-of-file found while reading from a file.
  • [ZIP_ER_INTERNAL]
    The callback function of an added or replaced file returned an error but failed to report which.
  • [ZIP_ER_INVAL]
    The path argument is NULL.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.
  • [ZIP_ER_NOZIP]
    File is not a zip archive.
  • [ZIP_ER_READ]
    A file read failed.
  • [ZIP_ER_RENAME]
    A temporary file could not be renamed to its final name.
  • [ZIP_ER_SEEK]
    A file seek failed.
  • [ZIP_ER_TMPOPEN]
    A temporary file could not be created.
  • [ZIP_ER_WRITE]
    A file write failed.
  • [ZIP_ER_ZLIB]
    An error occurred while (de)compressing a stream with zlib(3).

Additionally, any errors returned by the callback function for added or replaced files will be passed back.

SEE ALSO

libzip(3), zip_discard(3), zip_error_get(3), zip_fdopen(3), zip_open(3), zip_strerror(3)


zip_set_archive_comment(3)


NAME

zip_set_archive_comment — set zip archive comment

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_set_archive_comment(zip_t *archive, const char *comment, zip_uint16_t len);

DESCRIPTION

The zip_set_archive_comment() function sets the comment for the entire zip archive. If comment is NULL and len is 0, the archive comment will be removed. comment must be encoded in ASCII or UTF-8.

RETURN VALUES

Upon successful completion 0 is returned. Otherwise, -1 is returned and the error information in archive is set to indicate the error.

ERRORS

zip_set_archive_comment() fails if:

  • [ZIP_ER_INVAL]
    len is less than 0 or longer than the maximum comment length in a zip file (65535), or comment is not a valid UTF-8 encoded string.
  • [ZIP_ER_MEMORY]
    Required memory could not be allocated.

SEE ALSO

libzip(3), zip_get_archive_comment(3), zip_get_file_comment(3), zip_set_file_comment(3)


zip_set_archive_flag(3)


NAME

zip_set_archive_flag — set zip archive flag
LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_set_archive_flag(zip_t *archive, zip_flags_t flag, int value);

DESCRIPTION

The** zip_set_archive_flag() function sets the flag* flag*** for the archive archive to the value value.
Currently there are no supported flags.

RETURN VALUES

Upon successful completion 0 is returned, and -1 if an error occurred.

SEE ALSO

libzip(3), zip_get_archive_flag(3)


zip_error_to_str(3)


NAME

zip_error_to_str — get string representation of zip error

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_error_to_str(char *buf, zip_uint64_t len, int ze, int se);

DESCRIPTION

The function zip_error_to_str() is deprecated; use zip_error_init_with_code(3) and zip_error_strerror(3) instead.
Replace:

char buf[BUFSIZE]; 
zip_error_to_str(buf, sizeof(buf), ze, se); 
printf("%s", buf);

with:

zip_error_t error; 
zip_error_init_with_code(&error, ze); 
printf("%s", zip_error_strerror(&error)); 
zip_error_fini(&error);

SEE ALSO

libzip(3), zip_error_init_with_code(3), zip_error_strerror(3)


zip_strerror(3)

zip_file_strerror(3)


NAME

zip_file_strerror, zip_strerror — get string representation for a zip error

LIBRARY

libzip (-lzip)

SYNOPSIS

include <zip.h>
const char * zip_file_strerror(zip_file_t *file);
const char * zip_strerror(zip_t *archive);

DESCRIPTION

The zip_strerror() function returns a string describing the last error for the zip archive archive, while the zip_file_strerror() function does the same for a zip file file (one file in an archive). The returned string must not be modified or freed, and becomes invalid when archive or file, respectively, is closed or on the next call to zip_strerror() or zip_file_strerror(), respectively, for the same archive.

RETURN VALUES

zip_file_strerror() and zip_strerror() return a pointer to the error string.

SEE ALSO

libzip(3), zip_error_to_str(3)


zip_error_get(3)

zip_file_error_get(3)


NAME

zip_error_get, zip_file_error_get — get error codes for archive or file

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
void zip_error_get(zip_t *archive, int *zep, int *sep);
void zip_file_error_get(zip_file_t *file, int *zep, int *sep);

DESCRIPTION

The functions zip_error_get() and zip_file_error_get() are deprecated. Use zip_error_code_system(3), zip_error_code_zip(3), zip_file_get_error(3), and zip_get_error(3) instead.

For zip_error_get(), replace

int ze, se; 
zip_error_get(za, &ze, &se);

with

int ze, se; 
zip_error_t *error = zip_get_error(za); 
ze = zip_error_code_zip(error); 
se = zip_error_code_system(error);

For zip_file_error_get(), replace

int ze, se; 
zip_file_error_get(zf, &ze, &se);

with

int ze, se; 
zip_error_t *error = zip_file_get_error(zf); 
ze = zip_error_code_zip(error); 
se = zip_error_code_system(error);

SEE ALSO

libzip(3), zip_error_code_system(3), zip_error_code_zip(3), zip_file_get_error(3), zip_get_error(3)


zip_error_get_sys_type(3)


NAME

zip_error_get_sys_type — get type of system error code

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>
int zip_error_get_sys_type(int ze);

DESCRIPTION

The function zip_error_get_sys_type() is deprecated; use zip_error_init_with_code(3) and zip_error_system_type(3) instead.
Replace

int i = zip_error_get_sys_type(ze);

with

zip_error_t error; 
zip_error_init_with_code(&error, ze); 
int i = zip_error_system_type(&error);

SEE ALSO

libzip(3), zip_error_init_with_code(3), zip_error_system_type(3)


zip_errors(3)


NAME

zip_errors — list of all libzip error codes

LIBRARY

libzip (-lzip)

SYNOPSIS

#include <zip.h>

DESCRIPTION

The following error codes are used by libzip:

  • [ZIP_ER_OK]
    No error.
  • [ZIP_ER_MULTIDISK]
    Multi-disk zip archives not supported.
  • [ZIP_ER_RENAME]
    Renaming temporary file failed.
  • [ZIP_ER_CLOSE]
    Closing zip archive failed.
  • [ZIP_ER_SEEK]
    Seek error.
  • [ZIP_ER_READ]
    Read error.
  • [ZIP_ER_WRITE]
    Write error.
  • [ZIP_ER_CRC]
    CRC error.
  • [ZIP_ER_ZIPCLOSED]
    Containing zip archive was closed.
  • [ZIP_ER_NOENT]
    No such file.
  • [ZIP_ER_EXISTS]
    File already exists.
  • [ZIP_ER_OPEN]
    Can't open file.
  • [ZIP_ER_TMPOPEN]
    Failure to create temporary file.
  • [ZIP_ER_ZLIB]
    Zlib error.
  • [ZIP_ER_MEMORY]
    Malloc failure.
  • [ZIP_ER_CHANGED]
    Entry has been changed.
  • [ZIP_ER_COMPNOTSUPP]
    Compression method not supported.
  • [ZIP_ER_EOF]
    Premature EOF.
  • [ZIP_ER_INVAL]
    Invalid argument.
  • [ZIP_ER_NOZIP]
    Not a zip archive.
  • [ZIP_ER_INTERNAL]
    Internal error.
  • [ZIP_ER_INCONS]
    Zip archive inconsistent.
  • [ZIP_ER_REMOVE]
    Can't remove file.
  • [ZIP_ER_DELETED]
    Entry has been deleted.
  • [ZIP_ER_ENCRNOTSUPP]
    Encryption method not supported.
  • [ZIP_ER_RDONLY]
    Read-only archive.
  • [ZIP_ER_NOPASSWD]
    No password provided.
  • [ZIP_ER_WRONGPASSWD]
    Wrong password provided.
posted @ 2016-09-23 19:22 xiaobaiyey 阅读(...) 评论(...) 编辑 收藏