QIO(3)

💖 NAME 💖

okay so bestie, welcome to the QIO(3) Library Functions Manual page for qio — the quick I/O part of the InterNetNews library. it's giving fast little file-reading bestie energy 💅✨

✨ SYNOPSIS ✨

       #include "qio.h"

       QIOSTATE *
       QIOopen(name, size)
           char             *name;
           int              size;

       QIOSTATE *
       QIOfdopen(fd, size)
           int              fd;
           int              size;

       void
       QIOclose(qp)
           QIOSTATE         *qp;

       char *
       QIOread(qp)
           QIOSTATE         *qp;

       int
       QIOlength(qp)
           QIOSTATE         *qp;

       int
       QIOtoolong(qp)
           QIOSTATE         *qp;

       int
       QIOerror(qp)
           QIOSTATE         *qp;

       int
       QIOtell(qp)
           QIOSTATE         *qp;

       int
       QIOrewind(qp)
           QIOSTATE         *qp;

       int
       QIOfileno(qp)
           QIOSTATE         *qp;

🌸 DESCRIPTION 🌸

these routines are part of the InterNetNews library, libinn(3), and they're literally here to give you quick read access to files. the letters “QIO” stand for Quick I/O. no cap, that's the whole vibe 🦋

• QIOopen — opens the file name for reading. it uses a buffer of size bytes, which must also be larger than the longest expected line. the header file defines the constant QIO_BUFFER as a reasonable default. if size is zero, then QIOopen will call stat(2) and use the returned block size; if that fails it will use QIO_BUFFER. it returns NULL on error, or a pointer to a handle to be used in other calls. 🎀
• QIOfdopen — performs the same function except that fd refers to an already-open descriptor. iconic behavior honestly 💜
• QIOclose — closes the open file and releases any resources used by it. clean up your mess, bestie 🧚
• QIOread — returns a pointer to the next line in the file. the trailing newline will be replaced with a \0. if EOF is reached, an error occurs, or if the line is longer than the buffer, QIOread returns NULL. 😭
• QIOlength — after a successful call to QIOread, this returns the length of the current line. slay 💅
• QIOtoolong and QIOerror — these can be called after QIOread returns NULL to determine if there was an error, or if the line was too long. if QIOtoolong returns non-zero, then the current line did not fit in the buffer, and the next call to QIOread will try to read the rest of the line. long lines can only be discarded. if QIOerror returns non-zero, then a serious I/O error occurred. 🫶
• QIOtell — returns the lseek(2) offset at which the next line will start. 📍
• QIOrewind — sets the read pointer back to the beginning of the file. rewind era 🔁
• QIOfileno — returns the descriptor of the open file. 🔥

⚠️ bestie, long lines can only be discarded — no rescuing them, okay?

QIOlength, QIOtoolong, QIOerror, QIOtell, and QIOfileno are implemented as macro's defined in the header file. yup, macro magic 🌈

🎀 EXAMPLE 🎀

              QIOSTATE             *h;
              long                 offset;
              char                 *p;

              h = QIOopen("/etc/motd", QIO_BUFFER);
              for (offset = QIOtell(h); (p = QIOread(h)) != NULL; offset = QIOtell(h))
                  printf("At %ld, %s\n", offset, p);
              if (QIOerror(h)) {
                  perror("Read error");
                  exit(1);
              }
              QIOclose(h);

👑 HISTORY 👑

written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. this is revision 1.7, dated 1993/01/29. historic icon behavior 💖

mwah 💋 — source/version: QIO(3), revision 1.7, dated 1993/01/29. byeeee bestie, go read some files fast 🫶✨