---
name: "zip_source_function"
section: "3"
platform: "linux"
package: "libzip"
version: "1.11.4-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/zip_source_function"
---

# zip\_source\_function(3)

create data source from function

## NAME

**zip\_source\_function**, **zip\_source\_function\_create** – 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**() create 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.

  If your source uses any allocated memory (including *userdata*) it should also implement ZIP\_SOURCE\_FREE to avoid memory leaks.

- 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.

  On top of the above, supporting the pseudo-command ZIP\_SOURCE\_SUPPORTS\_REOPEN allows calling **zip\_source\_open**() again after calling **zip\_source\_close**().

### Dv ZIP\_SOURCE\_ACCEPT\_EMPTY

Return 1 if an empty source should be accepted as a valid zip archive. This is the default if this command is not supported by a source. File system backed sources should return 0.

### Dv ZIP\_SOURCE\_BEGIN\_WRITE

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

### Dv ZIP\_SOURCE\_BEGIN\_WRITE\_CLONING

Prepare the source for writing, keeping the first *len* bytes of the original file. Only implement this command if it is more efficient than copying the data, and if it does not destructively overwrite the original file (you still have to be able to execute ZIP\_SOURCE\_ROLLBACK\_WRITE).

The next write should happen at byte *offset*.

### Dv ZIP\_SOURCE\_CLOSE

Reading is done.

### Dv 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.

### Dv 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)](/zip_errors/3.md) for details on the error codes. If the source stores error information in a zip\_error\_t, use [zip\_error\_to\_data(3)](/zip_error_to_data/3.md) and return its return value. Otherwise, return 2 \* sizeof(int).

### Dv ZIP\_SOURCE\_FREE

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

### Dv ZIP\_SOURCE\_GET\_FILE\_ATTRIBUTES

Provide information about various data. Then the data should be put in the appropriate entry in the passed *zip\_file\_attributes\_t* argument, and the appropriate ZIP\_FILE\_ATTRIBUTES\_\* value must be or'ed into the *valid* member to denote that the corresponding data has been provided. A *zip\_file\_attributes\_t* structure can be initialized using [zip\_file\_attributes\_init(3)](/zip_file_attributes_init/3.md).

- ASCII mode

  If a file is a plaintext file in ASCII. Can be used by extraction tools to automatically convert line endings (part of the internal file attributes). Member *ascii*, flag ZIP\_FILE\_ATTRIBUTES\_ASCII.

- General Purpose Bit Flags (limited to Compression Flags)

  The general purpose bit flag in the zip in the local and central directory headers contain information about the compression method. Member *general\_purpose\_bit\_flags* and *general\_purpose\_bit\_mask* to denote which members have been set; flag ZIP\_FILE\_ATTRIBUTES\_GENERAL\_PURPOSE\_BIT\_FLAGS.

- External File Attributes

  The external file attributes (usually operating system-specific). Member *external\_file\_attributes*, flag ZIP\_FILE\_ATTRIBUTES\_EXTERNAL\_FILE\_ATTRIBUTES.

- Version Needed

  A minimum version needed required to unpack this entry (in the usual "major \* 10 + minor" format). Member *version\_needed*, flag ZIP\_FILE\_ATTRIBUTES\_VERSION\_NEEDED.

- Operating System

  One of the operating systems as defined by the ZIP\_OPSYS\_\* variables (see *zip.h*). This value affects the interpretation of the external file attributes. Member *host\_system*, flag ZIP\_FILE\_ATTRIBUTES\_HOST\_SYSTEM.

### Dv ZIP\_SOURCE\_OPEN

Prepare for reading.

### Dv ZIP\_SOURCE\_READ

Read data into the buffer *data* of size *len*. Return the number of bytes placed into *data* on success, and zero for end-of-file.

### Dv ZIP\_SOURCE\_REMOVE

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

### Dv 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.

### Dv ZIP\_SOURCE\_SEEK

Specify position to read next byte from, like [fseek(3)](/fseek/3.md). Use [ZIP\_SOURCE\_GET\_ARGS(3)](/ZIP_SOURCE_GET_ARGS/3.md) 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)](/zip_source_seek_compute_offset/3.md) to validate the arguments and compute the new offset.

### Dv ZIP\_SOURCE\_SEEK\_WRITE

Specify position to write next byte to, like [fseek(3)](/fseek/3.md). See ZIP\_SOURCE\_SEEK for details.

### Dv 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)](/zip_stat_init/3.md) and then filled in.

For uncompressed, unencrypted data, all information is optional. However, fill in as much information as is readily available.

If the data is compressed, ZIP\_STAT\_COMP\_METHOD, ZIP\_STAT\_SIZE, and ZIP\_STAT\_CRC must be filled in.

If the data is encrypted, ZIP\_STAT\_ENCRYPTION\_METHOD, ZIP\_STAT\_COMP\_METHOD, ZIP\_STAT\_SIZE, and ZIP\_STAT\_CRC must be filled in.

Information only available after the source has been read (e.g., size) can be omitted in an earlier call. *NOTE*: **zip\_source\_function**() may be called with this argument even after being called with ZIP\_SOURCE\_CLOSE.

Return sizeof(struct zip\_stat) on success.

### Dv ZIP\_SOURCE\_SUPPORTS

Return bitmap specifying which commands are supported. Use [zip\_source\_make\_command\_bitmap(3)](/zip_source_make_command_bitmap/3.md). If this command is not implemented, the source is assumed to be a read source without seek support.

### Dv ZIP\_SOURCE\_TELL

Return the current read offset in the source, like [ftell(3)](/ftell/3.md).

### Dv ZIP\_SOURCE\_TELL\_WRITE

Return the current write offset in the source, like [ftell(3)](/ftell/3.md).

### Dv ZIP\_SOURCE\_WRITE

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

### Dv ZIP\_SOURCE\_SUPPORTS\_REOPEN

This command is never actually invoked, support for it signals the ability to handle multiple open/read/close cycles.

### 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 or ZIP\_SOURCE\_BEGIN\_WRITE\_CLONING 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\_ACCEPT\_EMPTY, ZIP\_SOURCE\_GET\_FILE\_ATTRIBUTES, and 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 or ZIP\_SOURCE\_BEGIN\_WRITE\_CLONING 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)](/libzip/3.md), [zip\_file\_add(3)](/zip_file_add/3.md), [zip\_file\_attributes\_init(3)](/zip_file_attributes_init/3.md), [zip\_file\_replace(3)](/zip_file_replace/3.md), [zip\_source(5)](/zip_source/5.md), [zip\_stat\_init(3)](/zip_stat_init/3.md)

## HISTORY

**zip\_source\_function**() and **zip\_source\_function\_create**() were added in libzip 1.0.

## AUTHORS

Dieter Baron ⟨*dillo@nih.at*⟩ and Thomas Klausner ⟨*wiz@gatalith.at*⟩