Chiebot-Mirror
/
zlib
mirror of https://github.com/madler/zlib.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Clarify gz* function interfaces, referring to parameter names.

Browse Source
pull/563/head
Mark Adler 4 years ago
parent d71dc66fa8
commit e54494e6bc
1 changed files with 76 additions and 77 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 153
      zlib.h

153
zlib.h
Unescape View File

@ -1304,14 +1304,14 @@ typedef struct gzFile_s *gzFile; /* semi-opaque gzip file descriptor */
/* /*
ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode));
Opens a gzip (.gz) file for reading or writing. The mode parameter is as Open the gzip (.gz) file at path for reading and decompressing, or
in fopen ("rb" or "wb") but can also include a compression level ("wb9") or compressing and writing. The mode parameter is as in fopen ("rb" or "wb")
a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman-only but can also include a compression level ("wb9") or a strategy: 'f' for
compression as in "wb1h", 'R' for run-length encoding as in "wb1R", or 'F' filtered data as in "wb6f", 'h' for Huffman-only compression as in "wb1h",
for fixed code compression as in "wb9F". (See the description of 'R' for run-length encoding as in "wb1R", or 'F' for fixed code compression
deflateInit2 for more information about the strategy parameter.) 'T' will as in "wb9F". (See the description of deflateInit2 for more information
request transparent writing or appending with no compression and not using about the strategy parameter.) 'T' will request transparent writing or
the gzip format. appending with no compression and not using the gzip format.
"a" can be used instead of "w" to request that the gzip stream that will "a" can be used instead of "w" to request that the gzip stream that will
be written be appended to the file. "+" will result in an error, since be written be appended to the file. "+" will result in an error, since
@ -1341,9 +1341,9 @@ ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode));
ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode));
/* /*
gzdopen associates a gzFile with the file descriptor fd. File descriptors Associate a gzFile with the file descriptor fd. File descriptors are
are obtained from calls like open, dup, creat, pipe or fileno (if the file obtained from calls like open, dup, creat, pipe or fileno (if the file has
has been previously opened with fopen). The mode parameter is as in gzopen. been previously opened with fopen). The mode parameter is as in gzopen.
The next call of gzclose on the returned gzFile will also close the file The next call of gzclose on the returned gzFile will also close the file
descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor
@ -1364,13 +1364,13 @@ ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode));
ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size));
/* /*
Set the internal buffer size used by this library's functions. The Set the internal buffer size used by this library's functions for file to
default buffer size is 8192 bytes. This function must be called after size. The default buffer size is 8192 bytes. This function must be called
gzopen() or gzdopen(), and before any other calls that read or write the after gzopen() or gzdopen(), and before any other calls that read or write
file. The buffer memory allocation is always deferred to the first read or the file. The buffer memory allocation is always deferred to the first read
write. Three times that size in buffer space is allocated. A larger buffer or write. Three times that size in buffer space is allocated. A larger
size of, for example, 64K or 128K bytes will noticeably increase the speed buffer size of, for example, 64K or 128K bytes will noticeably increase the
of decompression (reading). speed of decompression (reading).
The new buffer size also affects the maximum length for gzprintf(). The new buffer size also affects the maximum length for gzprintf().
@ -1380,9 +1380,9 @@ ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size));
ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy));
/* /*
Dynamically update the compression level or strategy. See the description Dynamically update the compression level and strategy for file. See the
of deflateInit2 for the meaning of these parameters. Previously provided description of deflateInit2 for the meaning of these parameters. Previously
data is flushed before the parameter change. provided data is flushed before applying the parameter changes.
gzsetparams returns Z_OK if success, Z_STREAM_ERROR if the file was not gzsetparams returns Z_OK if success, Z_STREAM_ERROR if the file was not
opened for writing, Z_ERRNO if there is an error writing the flushed data, opened for writing, Z_ERRNO if there is an error writing the flushed data,
@ -1391,7 +1391,7 @@ ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy));
ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len));
/* /*
Reads the given number of uncompressed bytes from the compressed file. If Read and decompress up to len uncompressed bytes from file into buf. If
the input file is not in gzip format, gzread copies the given number of the input file is not in gzip format, gzread copies the given number of
bytes into the buffer directly from the file. bytes into the buffer directly from the file.
@ -1422,11 +1422,11 @@ ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len));
ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems, ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems,
gzFile file)); gzFile file));
/* /*
Read up to nitems items of size size from file to buf, otherwise operating Read and decompress up to nitems items of size size from file into buf,
as gzread() does. This duplicates the interface of stdio's fread(), with otherwise operating as gzread() does. This duplicates the interface of
size_t request and return types. If the library defines size_t, then stdio's fread(), with size_t request and return types. If the library
z_size_t is identical to size_t. If not, then z_size_t is an unsigned defines size_t, then z_size_t is identical to size_t. If not, then z_size_t
integer type that can contain a pointer. is an unsigned integer type that can contain a pointer.
gzfread() returns the number of full items read of size size, or zero if gzfread() returns the number of full items read of size size, or zero if
the end of the file was reached and a full item could not be read, or if the end of the file was reached and a full item could not be read, or if
@ -1445,18 +1445,16 @@ ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems,
file, reseting and retrying on end-of-file, when size is not 1. file, reseting and retrying on end-of-file, when size is not 1.
*/ */
ZEXTERN int ZEXPORT gzwrite OF((gzFile file, ZEXTERN int ZEXPORT gzwrite OF((gzFile file, voidpc buf, unsigned len));
voidpc buf, unsigned len));
/* /*
Writes the given number of uncompressed bytes into the compressed file. Compress and write the len uncompressed bytes at buf to file. gzwrite
gzwrite returns the number of uncompressed bytes written or 0 in case of returns the number of uncompressed bytes written or 0 in case of error.
error.
*/ */
ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size, ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size,
z_size_t nitems, gzFile file)); z_size_t nitems, gzFile file));
/* /*
gzfwrite() writes nitems items of size size from buf to file, duplicating Compress and write nitems items of size size from buf to file, duplicating
the interface of stdio's fwrite(), with size_t request and return types. If the interface of stdio's fwrite(), with size_t request and return types. If
the library defines size_t, then z_size_t is identical to size_t. If not, the library defines size_t, then z_size_t is identical to size_t. If not,
then z_size_t is an unsigned integer type that can contain a pointer. then z_size_t is an unsigned integer type that can contain a pointer.
@ -1469,22 +1467,22 @@ ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size,
ZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...)); ZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...));
/* /*
Converts, formats, and writes the arguments to the compressed file under Convert, format, compress, and write the arguments (...) to file under
control of the format string, as in fprintf. gzprintf returns the number of control of the string format, as in fprintf. gzprintf returns the number of
uncompressed bytes actually written, or a negative zlib error code in case uncompressed bytes actually written, or a negative zlib error code in case
of error. The number of uncompressed bytes written is limited to 8191, or of error. The number of uncompressed bytes written is limited to 8191, or
one less than the buffer size given to gzbuffer(). The caller should assure one less than the buffer size given to gzbuffer(). The caller should assure
that this limit is not exceeded. If it is exceeded, then gzprintf() will that this limit is not exceeded. If it is exceeded, then gzprintf() will
return an error (0) with nothing written. In this case, there may also be a return an error (0) with nothing written. In this case, there may also be a
buffer overflow with unpredictable consequences, which is possible only if buffer overflow with unpredictable consequences, which is possible only if
zlib was compiled with the insecure functions sprintf() or vsprintf() zlib was compiled with the insecure functions sprintf() or vsprintf(),
because the secure snprintf() or vsnprintf() functions were not available. because the secure snprintf() or vsnprintf() functions were not available.
This can be determined using zlibCompileFlags(). This can be determined using zlibCompileFlags().
*/ */
ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s));
/* /*
Writes the given null-terminated string to the compressed file, excluding Compress and write the given null-terminated string s to file, excluding
the terminating null character. the terminating null character.
gzputs returns the number of characters written, or -1 in case of error. gzputs returns the number of characters written, or -1 in case of error.
@ -1492,11 +1490,12 @@ ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s));
ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len));
/* /*
Reads bytes from the compressed file until len-1 characters are read, or a Read and decompress bytes from file into buf, until len-1 characters are
newline character is read and transferred to buf, or an end-of-file read, or until a newline character is read and transferred to buf, or an
condition is encountered. If any characters are read or if len == 1, the end-of-file condition is encountered. If any characters are read or if len
string is terminated with a null character. If no characters are read due is one, the string is terminated with a null character. If no characters
to an end-of-file or len < 1, then the buffer is left untouched. are read due to an end-of-file or len is less than one, then the buffer is
left untouched.
gzgets returns buf which is a null-terminated string, or it returns NULL gzgets returns buf which is a null-terminated string, or it returns NULL
for end-of-file or in case of error. If there was an error, the contents at for end-of-file or in case of error. If there was an error, the contents at
@ -1505,13 +1504,13 @@ ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len));
ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c));
/* /*
Writes c, converted to an unsigned char, into the compressed file. gzputc Compress and write c, converted to an unsigned char, into file. gzputc
returns the value that was written, or -1 in case of error. returns the value that was written, or -1 in case of error.
*/ */
ZEXTERN int ZEXPORT gzgetc OF((gzFile file)); ZEXTERN int ZEXPORT gzgetc OF((gzFile file));
/* /*
Reads one byte from the compressed file. gzgetc returns this byte or -1 Read and decompress one byte from file. gzgetc returns this byte or -1
in case of end of file or error. This is implemented as a macro for speed. in case of end of file or error. This is implemented as a macro for speed.
As such, it does not do all of the checking the other functions do. I.e. As such, it does not do all of the checking the other functions do. I.e.
it does not check to see if file is NULL, nor whether the structure file it does not check to see if file is NULL, nor whether the structure file
@ -1520,8 +1519,8 @@ ZEXTERN int ZEXPORT gzgetc OF((gzFile file));
ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file));
/* /*
Push one character back onto the stream to be read as the first character Push c back onto the stream for file to be read as the first character on
on the next read. At least one character of push-back is allowed. the next read. At least one character of push-back is always allowed.
gzungetc() returns the character pushed, or -1 on failure. gzungetc() will gzungetc() returns the character pushed, or -1 on failure. gzungetc() will
fail if c is -1, and may fail if a character has been pushed but not read fail if c is -1, and may fail if a character has been pushed but not read
yet. If gzungetc is used immediately after gzopen or gzdopen, at least the yet. If gzungetc is used immediately after gzopen or gzdopen, at least the
@ -1532,9 +1531,9 @@ ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file));
ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush));
/* /*
Flushes all pending output into the compressed file. The parameter flush Flush all pending output to file. The parameter flush is as in the
is as in the deflate() function. The return value is the zlib error number deflate() function. The return value is the zlib error number (see function
(see function gzerror below). gzflush is only permitted when writing. gzerror below). gzflush is only permitted when writing.
If the flush parameter is Z_FINISH, the remaining data is written and the If the flush parameter is Z_FINISH, the remaining data is written and the
gzip stream is completed in the output. If gzwrite() is called again, a new gzip stream is completed in the output. If gzwrite() is called again, a new
@ -1549,8 +1548,8 @@ ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush));
ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file,
z_off_t offset, int whence)); z_off_t offset, int whence));
Sets the starting position for the next gzread or gzwrite on the given Set the starting position to offset relative to whence for the next gzread
compressed file. The offset represents a number of bytes in the or gzwrite on file. The offset represents a number of bytes in the
uncompressed data stream. The whence parameter is defined as in lseek(2); uncompressed data stream. The whence parameter is defined as in lseek(2);
the value SEEK_END is not supported. the value SEEK_END is not supported.
@ -1567,18 +1566,18 @@ ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file,
ZEXTERN int ZEXPORT gzrewind OF((gzFile file)); ZEXTERN int ZEXPORT gzrewind OF((gzFile file));
/* /*
Rewinds the given file. This function is supported only for reading. Rewind file. This function is supported only for reading.
gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET).
*/ */
/* /*
ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file));
Returns the starting position for the next gzread or gzwrite on the given Return the starting position for the next gzread or gzwrite on file.
compressed file. This position represents a number of bytes in the This position represents a number of bytes in the uncompressed data stream,
uncompressed data stream, and is zero when starting, even if appending or and is zero when starting, even if appending or reading a gzip stream from
reading a gzip stream from the middle of a file using gzdopen(). the middle of a file using gzdopen().
gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR)
*/ */
@ -1586,22 +1585,22 @@ ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file));
/* /*
ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile file)); ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile file));
Returns the current offset in the file being read or written. This offset Return the current compressed (actual) read or write offset of file. This
includes the count of bytes that precede the gzip stream, for example when offset includes the count of bytes that precede the gzip stream, for example
appending or when using gzdopen() for reading. When reading, the offset when appending or when using gzdopen() for reading. When reading, the
does not include as yet unused buffered input. This information can be used offset does not include as yet unused buffered input. This information can
for a progress indicator. On error, gzoffset() returns -1. be used for a progress indicator. On error, gzoffset() returns -1.
*/ */
ZEXTERN int ZEXPORT gzeof OF((gzFile file)); ZEXTERN int ZEXPORT gzeof OF((gzFile file));
/* /*
Returns true (1) if the end-of-file indicator has been set while reading, Return true (1) if the end-of-file indicator for file has been set while
false (0) otherwise. Note that the end-of-file indicator is set only if the reading, false (0) otherwise. Note that the end-of-file indicator is set
read tried to go past the end of the input, but came up short. Therefore, only if the read tried to go past the end of the input, but came up short.
just like feof(), gzeof() may return false even if there is no more data to Therefore, just like feof(), gzeof() may return false even if there is no
read, in the event that the last read request was for the exact number of more data to read, in the event that the last read request was for the exact
bytes remaining in the input file. This will happen if the input file size number of bytes remaining in the input file. This will happen if the input
is an exact multiple of the buffer size. file size is an exact multiple of the buffer size.
If gzeof() returns true, then the read functions will return no more data, If gzeof() returns true, then the read functions will return no more data,
unless the end-of-file indicator is reset by gzclearerr() and the input file unless the end-of-file indicator is reset by gzclearerr() and the input file
@ -1610,7 +1609,7 @@ ZEXTERN int ZEXPORT gzeof OF((gzFile file));
ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); ZEXTERN int ZEXPORT gzdirect OF((gzFile file));
/* /*
Returns true (1) if file is being copied directly while reading, or false Return true (1) if file is being copied directly while reading, or false
(0) if file is a gzip stream being decompressed. (0) if file is a gzip stream being decompressed.
If the input file is empty, gzdirect() will return true, since the input If the input file is empty, gzdirect() will return true, since the input
@ -1631,8 +1630,8 @@ ZEXTERN int ZEXPORT gzdirect OF((gzFile file));
ZEXTERN int ZEXPORT gzclose OF((gzFile file)); ZEXTERN int ZEXPORT gzclose OF((gzFile file));
/* /*
Flushes all pending output if necessary, closes the compressed file and Flush all pending output for file, if necessary, close file and
deallocates the (de)compression state. Note that once file is closed, you deallocate the (de)compression state. Note that once file is closed, you
cannot call gzerror with file, since its structures have been deallocated. cannot call gzerror with file, since its structures have been deallocated.
gzclose must not be called more than once on the same file, just as free gzclose must not be called more than once on the same file, just as free
must not be called more than once on the same allocation. must not be called more than once on the same allocation.
@ -1656,10 +1655,10 @@ ZEXTERN int ZEXPORT gzclose_w OF((gzFile file));
ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum));
/* /*
Returns the error message for the last error which occurred on the given Return the error message for the last error which occurred on file.
compressed file. errnum is set to zlib error number. If an error occurred errnum is set to zlib error number. If an error occurred in the file system
in the file system and not in the compression library, errnum is set to and not in the compression library, errnum is set to Z_ERRNO and the
Z_ERRNO and the application may consult errno to get the exact error code. application may consult errno to get the exact error code.
The application must not modify the returned string. Future calls to The application must not modify the returned string. Future calls to
this function may invalidate the previously returned string. If file is this function may invalidate the previously returned string. If file is
@ -1672,7 +1671,7 @@ ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum));
ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); ZEXTERN void ZEXPORT gzclearerr OF((gzFile file));
/* /*
Clears the error and end-of-file flags for file. This is analogous to the Clear the error and end-of-file flags for file. This is analogous to the
clearerr() function in stdio. This is useful for continuing to read a gzip clearerr() function in stdio. This is useful for continuing to read a gzip
file that is being written concurrently. file that is being written concurrently.
*/ */

Write Preview
Loading…
Cancel
Save