lib/libz/zopen.3

   1 .\" Copyright (c) 2014 Xin LI <delphij@FreeBSD.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .Dd December 6, 2018
  25 .Dt ZOPEN 3
  26 .Os
  27 .Sh NAME
  28 .Nm zopen
  29 .Nd open a gzip compressed stream
  30 .Sh LIBRARY
  31 .Lb libz
  32 .Sh SYNOPSIS
  33 .Ft FILE *
  34 .Fn zopen "const char *path" "const char *mode"
  35 .Ft FILE *
  36 .Fn zdopen "int fd" "const char *mode"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn zopen
  40 function opens a gzip file whose name is the string pointed to by
  41 .Fa path
  42 and returns a stream which can be used to access the uncompressed contents
  43 of the file.
  44 The
  45 .Fn zdopen
  46 variant takes a gzip file referenced by the file descriptor
  47 .Fa fd ,
  48 analogous to
  49 .Xr fdopen 3 .
  50 They are wrappers around
  51 .Xr zlib 3
  52 and the standard stream I/O APIs.
  53 .Pp
  54 The argument
  55 .Fa mode
  56 has the same meaning as it does in
  57 .Xr fopen 3 .
  58 .Pp
  59 The
  60 .Fn zopen
  61 and
  62 .Fn zdopen
  63 functions will associate the read, write, seek and close
  64 functions of
  65 .Xr zlib 3
  66 with the returned stream.
  67 .Sh RETURN VALUES
  68 Upon successful completion
  69 .Fn zopen
  70 and
  71 .Fn zdopen
  72 return a
  73 .Tn FILE
  74 pointer.
  75 Otherwise,
  76 .Dv NULL
  77 is returned and the global variable
  78 .Va errno
  79 is set to indicate the error.
  80 .Sh ERRORS
  81 In addition to the errors documented for
  82 .Xr fopen 3
  83 and
  84 .Xr fdopen 3 ,
  85 the functions may also fail for:
  86 .Bl -tag -width Er
  87 .It Bq Er ENOMEM
  88 Insufficient memory is available.
  89 .El
  90 .Sh COMPATIBILITY
  91 The implementation of
  92 .Fn zopen
  93 function first appeared in
  94 .Nx 1.6
  95 and
  96 .Fx 4.5 .
  97 .Fn zdopen
  98 first appeared in
  99 .Fx 13.0 .
 100 These functions may not be portable to systems other than
 101 .Fx .
 102 .Sh SEE ALSO
 103 .Xr fdopen 3 ,
 104 .Xr fopen 3 ,
 105 .Xr funopen 3 ,
 106 .Xr zlib 3