Changeset View
Changeset View
Standalone View
Standalone View
lib/libz/zopen.3
Show All 17 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd March 5, 2014 | .Dd December 6, 2018 | ||||
.Dt ZOPEN 3 | .Dt ZOPEN 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm zopen | .Nm zopen | ||||
.Nd open a gzip compressed stream | .Nd open a gzip compressed stream | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libz | .Lb libz | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.Ft FILE * | .Ft FILE * | ||||
.Fn zopen "const char *path" "const char *mode" | .Fn zopen "const char *path" "const char *mode" | ||||
.Ft FILE * | |||||
.Fn zdopen "int fd" "const char *mode" | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn zopen | .Fn zopen | ||||
opens a gzip file whose name is the string pointed to by | function opens a gzip file whose name is the string pointed to by | ||||
.Fa path | .Fa path | ||||
and associates a stream with it. | and returns a stream which can be used to access the uncompressed contents | ||||
It is a wrapper around | of the file. | ||||
The | |||||
.Fn zdopen | |||||
variant takes a gzip file referenced by the file descriptor | |||||
.Fa fd , | |||||
analogous to | |||||
.Xr fdopen 3 . | |||||
They are wrappers around | |||||
.Xr zlib 3 | .Xr zlib 3 | ||||
and standard stream I/O APIs. | and the standard stream I/O APIs. | ||||
.Pp | .Pp | ||||
The argument | The argument | ||||
.Fa mode | .Fa mode | ||||
have the same meaning as it does in | has the same meaning as it does in | ||||
.Xr fopen 3 . | .Xr fopen 3 . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Nm | .Fn zopen | ||||
function will associate read, write, seek and close | and | ||||
.Fn zdopen | |||||
functions will associate the read, write, seek and close | |||||
functions of | functions of | ||||
.Xr zlib 3 | .Xr zlib 3 | ||||
after successfully opened a file with | with the returned stream. | ||||
.Xr funopen 3 | |||||
so that they will be used to read or write the new stream. | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
Upon successful completion | Upon successful completion | ||||
.Nm | .Fn zopen | ||||
returns a | and | ||||
.Fn zdopen | |||||
return a | |||||
.Tn FILE | .Tn FILE | ||||
pointer. | pointer. | ||||
Otherwise, | Otherwise, | ||||
.Dv NULL | .Dv NULL | ||||
is returned and the global variable | is returned and the global variable | ||||
.Va errno | .Va errno | ||||
is set to indicate the error. | is set to indicate the error. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
In addition to the errors documented for | In addition to the errors documented for | ||||
.Xr fopen 3 , | .Xr fopen 3 | ||||
the | and | ||||
.Nm | .Xr fdopen 3 , | ||||
function may also fail for: | the functions may also fail for: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er ENOMEM | .It Bq Er ENOMEM | ||||
Insufficient memory is available. | Insufficient memory is available. | ||||
.El | .El | ||||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||||
This implementation of | The implementation of | ||||
.Nm | .Fn zopen | ||||
function first appeared in | function first appeared in | ||||
.Nx 1.6 | .Nx 1.6 | ||||
and | and | ||||
.Fx 4.5 . | .Fx 4.5 . | ||||
The | .Fn zdopen | ||||
.Nm | first appeared in | ||||
function may not be portable to systems other than | .Fx 12.1 . | ||||
delphij: [Optional] I think you probably want to put 13.0 here initially and amend it to 12.1 when the… | |||||
These functions may not be portable to systems other than | |||||
.Fx . | .Fx . | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr fdopen 3 , | |||||
.Xr fopen 3 , | .Xr fopen 3 , | ||||
.Xr funopen 3 , | .Xr funopen 3 , | ||||
.Xr zlib 3 | .Xr zlib 3 |
[Optional] I think you probably want to put 13.0 here initially and amend it to 12.1 when the change was MFC'ed.