.\" zip_open.mdoc -- open zip archive
-.\" Copyright (C) 2003-2009 Dieter Baron and Thomas Klausner
+.\" Copyright (C) 2003-2022 Dieter Baron and Thomas Klausner
.\"
.\" This file is part of libzip, a library to manipulate ZIP archives.
.\" The authors can be contacted at <libzip@nih.at>
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd February 15, 2009
+.Dd June 18, 2022
.Dt ZIP_OPEN 3
.Os
.Sh NAME
-.Nm zip_open
+.Nm zip_open ,
+.Nm zip_open_from_source
.Nd open zip archive
.Sh LIBRARY
libzip (-lzip)
.Sh SYNOPSIS
.In zip.h
-.Ft struct zip *
+.Ft zip_t *
.Fn zip_open "const char *path" "int flags" "int *errorp"
+.Ft zip_t *
+.Fn zip_open_from_source "zip_source_t *zs" "int flags" "zip_error_t *ze"
.Sh DESCRIPTION
-The zip archive specified by
+The
+.Fn zip_open
+function opens the zip archive specified by
.Ar path
-is opened and a pointer to a
+and returns a pointer to a
.Ft struct zip ,
-used to manipulate the archive, is returned.
+used to manipulate the archive.
The
.Fa flags
are specified by
.Em or Ns No 'ing
the following values, or 0 for none of them.
.Bl -tag -offset indent -width ZIP_CHECKCONS
+.It Dv ZIP_CHECKCONS
+Perform additional stricter consistency checks on the archive, and
+error if they fail.
.It Dv ZIP_CREATE
Create the archive if it does not exist.
.It Dv ZIP_EXCL
Error if archive already exists.
-.It Dv ZIP_CHECKCONS
-Perform additional consistency checks on the archive, and error if
-they fail.
+.It Dv ZIP_TRUNCATE
+If archive exists, ignore its current contents.
+In other words, handle it the same way as an empty archive.
+.It Dv ZIP_RDONLY
+Open archive in read-only mode.
.El
.Pp
If an error occurs and
.Ar errorp
-is non-NULL, it will be set to the corresponding error code.
+is
+.Pf non- Dv NULL ,
+it will be set to the corresponding error code.
+.Pp
+The
+.Fn zip_open_from_source
+function opens a zip archive encapsulated by the zip_source
+.Fa zs
+using the provided
+.Fa flags .
+In case of error, the zip_error
+.Fa ze
+is filled in.
.Sh RETURN VALUES
Upon successful completion
.Fn zip_open
-returns a
+and
+.Fn zip_open_from_source
+return a
.Ft struct zip
pointer.
Otherwise,
.Dv NULL
is returned and
+.Fn zip_open
+sets
.Ar *errorp
-is set to indicate the error.
+to indicate the error, while
+.Fn zip_open_from source
+sets
+.Ar ze
+to indicate the error.
.Sh ERRORS
The archive specified by
.Ar path
is set.
.It Bq Er ZIP_ER_INCONS
Inconsistencies were found in the file specified by
-.Ar path
-and
+.Ar path .
+This error is often caused by specifying
.Dv ZIP_CHECKCONS
-was specified.
+but can also happen without it.
.It Bq Er ZIP_ER_INVAL
The
.Ar path
.Ar path
does not allow seeks.
.El
+For newly created archives,
+.Fn zip_open
+does not try to create the file; this is done when calling
+.Xr zip_close 3
+and any errors, like missing write permissions, will
+be reported then.
.Sh SEE ALSO
.Xr libzip 3 ,
.Xr zip_close 3 ,
-.Xr zip_error_to_str 3 ,
+.Xr zip_error_strerror 3 ,
.Xr zip_fdopen 3
+.Sh HISTORY
+.Fn zip_open
+and
+.Fn zip_open_from_source
+were added in libzip 1.0.
.Sh AUTHORS
.An -nosplit
-.An Dieter Baron Aq dillo@giga.or.at
+.An Dieter Baron Aq Mt dillo@nih.at
and
-.An Thomas Klausner Aq tk@giga.or.at
+.An Thomas Klausner Aq Mt tk@giga.or.at
projects / platform / upstream / libzip.git / blobdiff