Linux repositories inspector

fzopen(3)

Version 1.06
Apr 20, 2006

libzio-devel

Libzio development files

NAME

fzopen - stream open functions on compressed files
fdzopen - stream open functions on compressed files

SYNOPSIS

#include <zio.h>
FILE *fzopen (const char *path, const char *mode);
FILE *fdzopen (int fildes, const char *mode, const char *what);

DESCRIPTION

The fzopen function opens the compressed file whose name is the string to by path and associates a stream with it. The fdopen function associates a stream for the existing files descriptor fildes for a compressed file.
The argument mode points to a string beginning with one of the following sequences (Additional characters may follow these sequences.):
r Open compressed text file for reading. The stream is positioned at the beginning of the file.
w Truncate file to zero length or create compressed text file for writing. The stream is positioned at the beginning of the file.
w1-9 Just like above but provides also the compression level.
The argument what of the function fdzopen specifies the underlying compression method which should be used:
g,z The file descriptor points to a gziped file.
b The file descriptor points to a bzip2ed file.
l The file descriptor points to a lzma2ed file.
Z The file descriptor points to a file in LZW format.
Note that fzopen and fdzopen can only open a compressed text file for reading or writing, but both, which means that the + is not possible. Nor can any compressed text file open for appending, which makes a not usable with fzopen.

NOTE

The program using libzio with -lzio at linking time should also be linked with the appropriate library for accessing compressed text files. This is the libz with -lz for accessing gziped text files and/or with -lbz2 for accessing bzip2ed text files.
For writing gzip/bzip2 files, fzopen only supports the suffixes .z and .gz for gzipped files and .bz2 for bzip2ed files. All supported formats can be found in the following table:
fread fwrite fseek suffix library
gzip yes yes yes .gz -lz
bzip2 yes yes yes .bz2 -lbz2
LZW yes no yes .Z builtin
lzma yes yes(no) yes .lzma -llzma (-llzmadec)
xz yes yes yes .xz -llzma
On reading first the appropriate suffixes are checked if not provided. If no file is found the magic byte sequence at the beginning of the file is checked to detect a gzip or bzip2 file.

CONFIGURATION

With the help of autoconf(1) or autoreconf(1) and a few lines in the common file configure.in or configure.ac found in many source packages a programmer or maintainer can extend the automatic configuration to find the appropriate libraries together with the libzio:
AC_CHECK_HEADER(zio.h, [
  AC_CHECK_LIB(zio, fzopen, [
    AC_CHECK_LIB(zio, fdzopen, [LIBS="$LIBS -lzio"; am_cv_libzio=yes])
  ])
])
if test "$am_cv_libzio" = yes; then
  am_cv_libzio=with
  AC_DEFINE(HAVE_ZIO, 1, [Define if you have libzio for opening compressed files.])
  AC_CHECK_HEADER(zlib.h, [
    for lib in z gz; do
      AC_CHECK_LIB($lib, gzopen, [
        LIBS="$LIBS -l$lib"
        am_cv_libzio="$am_cv_libzio lib$lib"
        break
      ])
    done
  ])
  AC_CHECK_HEADER(bzlib.h, [
    for lib in bz2 bzip2; do
      AC_CHECK_LIB($lib, BZ2_bzopen, [
        LIBS="$LIBS -l$lib"
        am_cv_libzio="$am_cv_libzio lib$lib"
        break
      ])
    done
  ])
  AC_CHECK_HEADER(lzmadec.h, [
    for lib in lzma lzmadec; do
      AC_CHECK_LIB($lib, lzmadec_open, [
        LIBS="$LIBS -l$lib"
        am_cv_libzio="$am_cv_libzio lib$lib"
        break
      ])
    done
  ])
  AC_CHECK_HEADER(lzma.h, [
    for lib in lzma; do
      AC_CHECK_LIB($lib, lzma_easy_encoder, [
        LIBS="$LIBS -l$lib"
        am_cv_libzio="$am_cv_libzio lib$lib"
        break
      ])
    done
  ])
  AC_MSG_NOTICE([libzio is used [$]am_cv_libzio])
fi
combined with two lines in the common file config.h.in like
/* Define to 1 if you have libzio for opening compressed files */
#undef HAVE_ZIO
(automatically added by autoreconf(1)) it is easy to use the cpp(1) macro HAVE_ZIO for the usage of fzopen instead of fopen(3).

RETURN VALUES

Upon successful completion fzopen return a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.

ERRORS

EINVAL The mode provided to fzopen was invalid.
ENOSYS The program using fzopen is not linked with the appropriate library (-lz for gziped files and -lbz2 for bzip2ed files.)
ENOTSUP
The program using fzopen has specified a wrong mode for a .bz2 files or has opened a .Z file for writing.
ENOMEM The call of the library functions of the libz or libbz2 fails due failed memory allocation.
ESPIPE This happens if fseek(3) is used in the case of seesking files is not supported.

WARNINGS

The functions fileno(3) or freopen(3) may not be applied on streams opened by fzopen. An further explanation will be found in section BUGS.

BUGS

Fzopen can not seek within bzip2 files due to the fact that the libbz2 does not provide a function like libz does with gzseek. .Z compressed file will be opened by fzopen and fzdopen only for reading. Also a seek is not possible for .Z files. .lzma compressed file will be opened by fzopen and fzdopen only for reading as the liblzmadec only supports reading. As the fzopen and fdzopen are custom-made streams created with the help of fopencookie(3) function of the glibc or funopen(3) known from BSD Systems it is not possible to use the file descriptor with e.g. fileno(3) in combination with system calls like read(2) as this will evade the underlying read/write functions of the e.g. libz.

FILES

/usr/include/zio.h

SEE ALSO

fopen(3),
fopencookie(3)
funopen(3)
gzip(1),
bzip2(1),
lzma(1),
xz(1),
/usr/include/zlib.h,
/usr/include/bzlib.h.
/usr/include/lzma.h.
/usr/include/lzmadec.h.

COPYRIGHT

2004 Werner Fink, 2004 SuSE LINUX AG Nuernberg, Germany.
2006,2008,2009 Werner Fink, 2006,2008,2009 SuSE Products GmbH, Germany.

AUTHOR

Werner Fink <>
⇧ Top