fzopen(3)

📦 version 1.09, in opensuse-leap 16.0

💅 fzopen(3) — Linux Programmer's Manual (but make it cute) 🎀

okay so this one's from the Linux Programmer's Manual, bestie, and it's literally all about opening compressed files as streams. two functions, one vibe. let's go ✨

🌸 NAME 🌸

  • fzopen — stream open functions on compressed files
  • fdzopen — stream open functions on compressed files

(yes they're the same tagline, they're twins, it's giving main character energy 👯‍♀️)

✨ SYNOPSIS ✨

#include <zio.h>

FILE *fzopen (const char *path, const char *mode);
FILE *fdzopen (int fildes, const char *mode, const char *what);

like, just #include <zio.h> and you're in 💖

🦋 DESCRIPTION 🦋

so fzopen opens the compressed file whose name is the string pointed to by path and associates a stream with it. and fdopen— no wait, fdzopen— associates a stream for the existing file descriptor fildes for a compressed file. same energy, different entry point 🫶

the mode argument points to a string beginning with one of these sequences (and yeah, extra characters can follow these sequences, no biggie):

  • r — open compressed text file for reading. the stream is positioned at the beginning of the file. classic. 💅
  • 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. so like w9 = max effort, she's trying 💀

and the what argument of fdzopen specifies the underlying compression method that 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.
  • x — the file descriptor points to a xz2ed file.
  • s — the file descriptor points to a file in zst format.
  • Z — the file descriptor points to a file in LZW format.
⚠️ heads up: fzopen and fdzopen can only open a compressed text file for reading or writing, but not both — which means the + is not possible. and no compressed text file can be opened for appending either, which makes a not usable with fzopen. sorry babe, no append arc 😭

🎀 NOTE 🎀

the program using libzio with -lzio at linking time should also be linked with the appropriate library for accessing compressed text files. that's libz with -lz for accessing gziped text files and/or -lbz2 for accessing bzip2ed text files. don't skip this step i'm begging 🙈

for writing gzip/bzip2 files, fzopen only supports the suffixes .z and .gz for gzipped files and .bz2 for bzip2ed files. all the supported formats are in this little legend right here — the original had it as a table but we're doing bullet core now, and every cell is preserved, no cap 👑

  • gzip — fread: yes · fwrite: yes · fseek: yes · suffix: .gz · library: -lz
  • bzip2 — fread: yes · fwrite: yes · fseek: yes · suffix: .bz2 · library: -lbz2
  • LZW — fread: yes · fwrite: no · fseek: yes · suffix: .Z · library: builtin
  • lzma — fread: yes · fwrite: yes(no) · fseek: yes · suffix: .lzma · library: -llzma (-llzmadec)
  • xz — fread: yes · fwrite: yes · fseek: yes · suffix: .xz · library: -llzma
  • zstd — fread: yes · fwrite: yes · fseek: no · suffix: .zst · library: -lzstd

on reading, first the appropriate suffixes are checked if not provided. and if no file is found, the magic byte sequence at the beginning of the file is checked to detect a gzip or bzip2 file. detective work, iconic 🔍

🧚 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_CHECK_HEADER(zstd.h, [
    for lib in lzstd; do
      AC_CHECK_LIB($lib, ZSTD_createCStream, [
        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). glow up complete ✨

💜 RETURN VALUES 💜

upon successful completion fzopen returns a FILE pointer. otherwise, NULL is returned and the global variable errno is set to indicate the error. that's the whole thing. simple. slay.

🔥 ERRORS 🔥

  • EINVAL — the mode provided to fzopen was invalid. bestie that mode made no sense 😭
  • ENOSYS — the program using fzopen is not linked with the appropriate library (-lz for gziped files and -lbz2 for bzip2ed files). you forgot the link, we've all been there 💀
  • ENOTSUP — the program using fzopen has specified a wrong mode for a .bz2 files or has opened a .Z file for writing. wrong vibe for that format, respectfully 🚫
  • ENOMEM — the call of the library functions of the libz or libbz2 fails due failed memory allocation. out of memory, not her fault 🙈
  • ESPIPE — this happens if fseek(3) is used in the case of seesking files is not supported. i.e. you tried to seek where seeking isn't a thing, and the system said "no ❤️"

⚠️ 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. like literally do not do it, i'm serious 🫶

💀 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. rip 😔
  • .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. read-only queen 👑
  • as the fzopen and fdzopen are custom-made streams created with the help of the 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. fr fr do not try it 💅

🌈 FILES 🌈

  • /usr/include/zio.h

⭐ SEE ALSO ⭐

  • 2004 Werner Fink, 2004 SuSE LINUX AG Nuernberg, Germany.
  • 2006,2008,2009 Werner Fink, 2006,2008,2009 SuSE Products GmbH, Germany.
  • 2021 Werner Fink, 2021 SUSE Software Solutions Germany GmbH, Germany.

👑 AUTHOR 👑

Werner Fink <werner@suse.de>

and that's the whole page, bestie — brought to you by the 3rd Berkeley Distribution, dated Apr 20, 2006, and honestly? it ate. now go compress something responsibly 💜🎀✨

📦 where this page comes from