fzopen.3.in

   1 '\" t -*- coding: UTF-8 -*-
   2 .\"
   3 .\" Copyright 2004 Werner Fink, 2004 SuSE LINUX AG, Germany.
   4 .\" Copyright 2006 Werner Fink, 2006 SuSE Products GmbH, Germany.
   5 .\" Copyright 2008 Werner Fink, 2008 SuSE Products GmbH, Germany.
   6 .\" Copyright 2009 Werner Fink, 2009 SuSE Products GmbH, Germany.
   7 .\"
   8 .\" This program is free software; you can redistribute it and/or modify
   9 .\" it under the terms of the GNU General Public License as published by
  10 .\" the Free Software Foundation; either version 2 of the License, or
  11 .\" (at your option) any later version.
  12 .\"
  13 .TH fzopen 3 "Apr 20, 2006" "Version @@VERSION@@" " Linux Programmer's Manual"
  14 .UC 3
  15 .OS SuSE Linux
  16 .SH NAME
  17 fzopen \- stream open functions on compressed files
  18 .br
  19 fdzopen \- stream open functions on compressed files
  20 .SH SYNOPSIS
  21 .\"
  22 .B #include <zio.h>
  23 .sp
  24 .BI "FILE *fzopen (const char *" path ", const char *" mode );
  25 .br
  26 .BI "FILE *fdzopen (int " fildes ", const char *" mode ", const char *" what );
  27 .SH DESCRIPTION
  28 The
  29 .B fzopen
  30 function opens the compressed file whose name is the string to by
  31 .I path
  32 and associates a stream with it.
  33 The
  34 .B fdopen
  35 function associates a stream for the existing files descriptor
  36 .I fildes
  37 for a compressed file.
  38 .PP
  39 The argument
  40 .I mode
  41 points to a string beginning with one of the following sequences
  42 (Additional characters may  follow these sequences.):
  43 .TP
  44 .B r
  45 Open compressed text file for reading.  The stream is positioned
  46 at the beginning of the file.
  47 .TP
  48 .B w
  49 Truncate file to zero length or create compressed text file for writing.
  50 The stream is positioned at the beginning of the file.
  51 .TP
  52 .BR w1 - 9
  53 Just like above but provides also the compression level.
  54 .PP
  55 The argument
  56 .I what
  57 of the function
  58 .B fdzopen
  59 specifies the underlying compression method which should be used:
  60 .TP
  61 .BR g , z
  62 The file descriptor points to a gziped file.
  63 .TP
  64 .BR b
  65 The file descriptor points to a bzip2ed file.
  66 .TP
  67 .BR l
  68 The file descriptor points to a lzma2ed file.
  69 .TP
  70 .BR Z
  71 The file descriptor points to a file in LZW format.
  72 .PP
  73 Note that
  74 .B fzopen
  75 and
  76 .B fdzopen
  77 can only open a compressed text file for reading
  78 .B or
  79 writing, but
  80 .IR both ,
  81 which means that the
  82 .B +
  83 is not possible.  Nor can any compressed text file open for appending,
  84 which makes
  85 .B a
  86 not usable with
  87 .BR fzopen .
  88 .\"
  89 .SH NOTE
  90 The program using libzio with
  91 .B -lzio
  92 at linking time should also be linked with
  93 the appropriate library for accessing compressed
  94 text files.  This is the libz with
  95 .B -lz
  96 for accessing gziped text files and/or with
  97 .B -lbz2
  98 for accessing bzip2ed text files.
  99 .PP
 100 For writing gzip/bzip2 files,
 101 .B fzopen
 102 only supports the suffixes
 103 .IR .z " and ".gz
 104 for gzipped files and
 105 .I .bz2
 106 for bzip2ed files. All supported formats can be found in
 107 the following table:
 108 .IP
 109 .TS H
 110 allbox;
 111 c  l l l l l
 112 rb l l l l l.
 113         fread   fwrite  fseek   suffix  library
 114 gzip    yes     yes     yes     .gz     -lz
 115 bzip2   yes     yes     yes     .bz2    -lbz2
 116 LZW     yes     no      yes     .Z       builtin
 117 lzma    yes     yes(no) yes     .lzma   -llzma (-llzmadec)
 118 xz      yes     yes     yes     .xz     -llzma
 119 .TE
 120 .PP
 121 .PP
 122 On reading first the appropriate suffixes are checked
 123 if not provided. If no file is found the magic
 124 byte sequence at the beginning of the file is checked
 125 to detect a gzip or bzip2 file.
 126 .PP
 127 .\"
 128 .SH CONFIGURATION
 129 With the help of
 130 .BR autoconf (1)
 131 or
 132 .BR autoreconf (1)
 133 and a few lines in the common file
 134 .B configure.in
 135 or
 136 .B configure.ac
 137 found in many source packages a programmer or maintainer
 138 can extend the automatic configuration to find the
 139 appropriate libraries together with the libzio:
 140 .PP
 141 .IP
 142 .nf
 143 AC_CHECK_HEADER(zio.h, [
 144   AC_CHECK_LIB(zio, fzopen, [
 145     AC_CHECK_LIB(zio, fdzopen, [LIBS="$LIBS -lzio"; am_cv_libzio=yes])
 146   ])
 147 ])
 148 if test "$am_cv_libzio" = yes; then
 149   am_cv_libzio=with
 150   AC_DEFINE(HAVE_ZIO, 1, [Define if you have libzio for opening compressed files.])
 151   AC_CHECK_HEADER(zlib.h, [
 152     for lib in z gz; do
 153       AC_CHECK_LIB($lib, gzopen, [
 154         LIBS="$LIBS -l$lib"
 155         am_cv_libzio="$am_cv_libzio lib$lib"
 156         break
 157       ])
 158     done
 159   ])
 160   AC_CHECK_HEADER(bzlib.h, [
 161     for lib in bz2 bzip2; do
 162       AC_CHECK_LIB($lib, BZ2_bzopen, [
 163         LIBS="$LIBS -l$lib"
 164         am_cv_libzio="$am_cv_libzio lib$lib"
 165         break
 166       ])
 167     done
 168   ])
 169   AC_CHECK_HEADER(lzmadec.h, [
 170     for lib in lzma lzmadec; do
 171       AC_CHECK_LIB($lib, lzmadec_open, [
 172         LIBS="$LIBS -l$lib"
 173         am_cv_libzio="$am_cv_libzio lib$lib"
 174         break
 175       ])
 176     done
 177   ])
 178   AC_CHECK_HEADER(lzma.h, [
 179     for lib in lzma; do
 180       AC_CHECK_LIB($lib, lzma_easy_encoder, [
 181         LIBS="$LIBS -l$lib"
 182         am_cv_libzio="$am_cv_libzio lib$lib"
 183         break
 184       ])
 185     done
 186   ])
 187   AC_MSG_NOTICE([libzio is used [$]am_cv_libzio])
 188 fi
 189 .fi
 190 .PP
 191 combined with two lines in the common file
 192 .B config.h.in
 193 like
 194 .PP
 195 .RS 1c
 196 .nf
 197 /* Define to 1 if you have libzio for opening compressed files */
 198 #undef HAVE_ZIO
 199 .fi
 200 .RE
 201 .PP
 202 (automatically added by
 203 .BR autoreconf (1))
 204 it is easy to use the
 205 .BR cpp (1)
 206 macro
 207 .I HAVE_ZIO
 208 for the usage of
 209 .B fzopen
 210 instead of
 211 .BR fopen (3).
 212 .PP
 213 .\"
 214 .SH RETURN VALUES
 215 Upon  successful  completion
 216 .B fzopen
 217 return a
 218 .B FILE
 219 pointer. Otherwise,
 220 .B NULL
 221 is returned and the global variable errno is set to
 222 indicate the error.
 223 .\"
 224 .SH ERRORS
 225 .TP
 226 .B EINVAL
 227 The
 228 .I mode
 229 provided to
 230 .B fzopen
 231 was invalid.
 232 .TP
 233 .B ENOSYS
 234 The program using
 235 .B fzopen
 236 is not linked with the appropriate library
 237 .RB ( -lz
 238 for gziped files and
 239 .B -lbz2
 240 for bzip2ed files.)
 241 .TP
 242 .B ENOTSUP
 243 The program using
 244 .B fzopen
 245 has specified a wrong mode for a
 246 .B .bz2
 247 files
 248 or has opened a
 249 .B .Z
 250 file for writing.
 251 .TP
 252 .B ENOMEM
 253 The call of the library functions of the
 254 .B libz
 255 or
 256 .B libbz2
 257 fails due failed memory allocation.
 258 .TP
 259 .B ESPIPE
 260 This happens if
 261 .BR fseek (3)
 262 is used in the case of seesking files is not
 263 supported.
 264 .\"
 265 .SH WARNINGS
 266 The functions
 267 .BR fileno (3)
 268 or
 269 .BR freopen (3)
 270 may not be applied on streams opened by
 271 .BR fzopen .
 272 An further explanation will be found in section
 273 .BR BUGS .
 274 .\"
 275 .SH BUGS
 276 .B Fzopen
 277 can not seek within
 278 .I bzip2
 279 files due to the fact that the
 280 .B libbz2
 281 does not provide a function like
 282 .I libz
 283 does with
 284 .BR gzseek .
 285 .B .Z
 286 compressed file will be opened by
 287 .B fzopen
 288 and
 289 .B fzdopen
 290 only for reading.  Also a seek
 291 is not possible for
 292 .B .Z
 293 files.
 294 .B .lzma
 295 compressed file will be opened by
 296 .B fzopen
 297 and
 298 .B fzdopen
 299 only for reading as the liblzmadec only
 300 supports reading.
 301 As the
 302 .B fzopen
 303 and
 304 .B fdzopen
 305 are custom-made streams created with the help of
 306 .BR fopencookie (3)
 307 function of the
 308 .B glibc
 309 or
 310 .BR funopen (3)
 311 known from BSD Systems
 312 it is not possible to use the file descriptor with e.g.
 313 .BR fileno (3)
 314 in combination with system calls like
 315 .BR read (2)
 316 as this will evade the underlying read/write
 317 functions of the e.g.
 318 .BR libz .
 319 .SH FILES
 320 .\"
 321 .BR /usr/include/zio.h
 322 .SH SEE ALSO
 323 .BR fopen (3),
 324 .br
 325 .BR fopencookie (3)
 326 .br
 327 .BR funopen (3)
 328 .br
 329 .BR gzip (1),
 330 .br
 331 .BR bzip2 (1),
 332 .br
 333 .BR lzma (1),
 334 .br
 335 .BR xz (1),
 336 .br
 337 .BR /usr/include/zlib.h ,
 338 .br
 339 .BR /usr/include/bzlib.h .
 340 .br
 341 .BR /usr/include/lzma.h .
 342 .br
 343 .BR /usr/include/lzmadec.h .
 344 .SH COPYRIGHT
 345 2004 Werner Fink,
 346 2004 SuSE LINUX AG Nuernberg, Germany.
 347 .br
 348 2006,2008,2009 Werner Fink,
 349 2006,2008,2009 SuSE Products GmbH, Germany.
 350 .SH AUTHOR
 351 Werner Fink <werner@suse.de>