QIODevice(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

✨ NAME ✨

QIODevice — the base class of I/O devices 💖

(yes bestie, this is the QIODevice(3qt) manual — part one of the saga, more coming, don't you dare leave 🫶)

🌈 SYNOPSIS 🌈

Ok so first things first, the vibe check: all the functions in this class are reentrant when Qt is built with thread support. (and yes, the original really does leave a stray </p> dangling off the end of that sentence — we stan a typo that made it to print 💀)

#include <qiodevice.h>

Inherited by QBuffer, QFile, QSocket, and QSocketDevice.

👑 Public Members

  • typedef Q_ULONG Offset
  • QIODevice ()
  • virtual ~QIODevice ()
  • int flags () const
  • int mode () const
  • int state () const
  • bool isDirectAccess () const
  • bool isSequentialAccess () const
  • bool isCombinedAccess () const
  • bool isBuffered () const
  • bool isRaw () const
  • bool isSynchronous () const
  • bool isAsynchronous () const
  • bool isTranslated () const
  • bool isReadable () const
  • bool isWritable () const
  • bool isReadWrite () const
  • bool isInactive () const
  • bool isOpen () const
  • int status () const
  • void resetStatus ()
  • virtual bool open ( int mode ) = 0
  • virtual void close () = 0
  • virtual void flush () = 0
  • virtual Offset size () const = 0
  • virtual Offset at () const
  • virtual bool at ( Offset pos )
  • virtual bool atEnd () const
  • bool reset ()
  • virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen ) = 0
  • virtual Q_LONG writeBlock ( const char * data, Q_ULONG len ) = 0
  • virtual Q_LONG readLine ( char * data, Q_ULONG maxlen )
  • Q_LONG writeBlock ( const QByteArray & data )
  • virtual QByteArray readAll ()
  • virtual int getch () = 0
  • virtual int putch ( int ch ) = 0
  • virtual int ungetch ( int ch ) = 0

🎀 Protected Members

  • void setFlags ( int flags )
  • void setType ( int type )
  • void setMode ( int mode )
  • void setState ( int state )
  • void setStatus ( int s )

🦋 DESCRIPTION 🦋

So, QIODevice? It's the base class of I/O devices. Like, the blueprint. The blueprint's blueprint, even.

An I/O device is basically a medium you can read bytes from and/or write bytes to. QIODevice is the abstract superclass of every single one of those devices — classes like QFile, QBuffer and QSocket inherit from QIODevice and then implement virtual functions such as write() however they need to. It's giving ✨template method pattern✨ and honestly? Iconic.

Now, apps can use QIODevice directly, but bestie, it is usually better to use QTextStream and QDataStream, because those give you stream operations on any QIODevice subclass. QTextStream is your text-oriented stream friend (think human-readable ASCII files, etc.), while QDataStream handles binary data in a totally platform-independent way. Pick your fighter 💅

The public member functions in QIODevice roughly split into two groups: the action functions and the state access functions. The most important action functions are:

  • open() — opens a device for reading and/or writing, depending on the mode argument.
  • close() — closes the device and tidies up (e.g. flushes buffered data).
  • readBlock() — reads a block of data from the device.
  • writeBlock() — writes a block of data to the device.
  • readLine() — reads a line (of text, usually) from the device.
  • flush() — makes sure all buffered data actually gets written to the real device.

There are also some other, less-used, action functions:

  • getch() — reads a single character.
  • ungetch() — forgets the last call to getch(), if possible.
  • putch() — writes a single character.
  • size() — returns the size of the device, if there is one.
  • at() — returns the current read/write pointer's position, if there is one for this device, or it moves the pointer if you give it an offset.
  • atEnd() — tells you whether there's more to read, if that's even meaningful for this device.
  • reset() — moves the read/write pointer back to the start of the device, if that's possible for this device.

The state access functions are all the "get" ones. A QIODevice subclass calls setState() to update the state, and then these simple access functions tell whoever's using the device what its state actually is. Here are the settings and their associated access functions:

  • Access type. Some devices are direct access (you can read/write anywhere), while others are sequential. QIODevice gives you the access functions (isDirectAccess(), isSequentialAccess(), and isCombinedAccess()) so you can find out what a given I/O device supports.
  • Buffering. Some devices are accessed in raw mode, others are buffered. Buffering usually gives you greater efficiency, especially for small read/write operations. isBuffered() tells you whether a given device is buffered. (This can often be set by the application in the call to open().)
  • Synchronicity. Synchronous devices work immediately (files, for example — you read from a file and the file delivers its data straight away). Other kinds of device, like a socket connected to an HTTP server, might not deliver the data until seconds after you asked to read it. isSynchronous() and isAsynchronous() tell you how this device operates.
  • CR/LF translation. For simplicity, applications often like to see just a single CR/LF style, and QIODevice subclasses can provide that. isTranslated() returns TRUE if this object translates CR/LF to just LF. (This can often be set by the application in the call to open().)
  • Permissions. Some files just cannot be written. For example, isReadable(), isWritable() and isReadWrite() tell the application whether it can read from and write to a given device. (This can often be set by the application in the call to open().)

And finally, isOpen() returns TRUE if the device is open, i.e. after an open() call. 🫶

QIODevice also provides numerous pure virtual functions that you need to implement when subclassing it. Here's a skeleton subclass with all the members you're sure to need, plus some you'll probably need:

class MyDevice : public QIODevice
{
public:
    MyDevice();
    ~MyDevice();
    bool open( int mode );
    void close();
    void flush();
    uint size() const;
    int  at() const;        // non-pure virtual
    bool at( int );         // non-pure virtual
    bool atEnd() const;     // non-pure virtual
    int readBlock( char *data, uint maxlen );
    int writeBlock( const char *data, uint len );
    int readLine( char *data, uint maxlen );
    int getch();
    int putch( int );
    int ungetch( int );
};

The three non-pure virtual functions don't need to be reimplemented for sequential devices. Noted, no cap 💅

See also: QDataStream, QTextStream, and Input/Output and Networking.

🧚 MEMBER TYPE DOCUMENTATION 🧚

QIODevice::Offset

The offset within the device. That's it, that's the whole thing 🌸

💖 MEMBER FUNCTION DOCUMENTATION 💖

QIODevice::QIODevice ()

Constructs an I/O device. Fresh out the box, baby device ✨

QIODevice::~QIODevice () [virtual]

Destroys the I/O device. Rest in peace, little guy 🕊️

Offset QIODevice::at () const [virtual]

Virtual function that returns the current I/O device position.

This is the position of the data read/write head of the I/O device. Like a little cursor going "you are here" 📍

  • See also: size()
  • Example: distributor/distributor.ui.h
  • Reimplemented in: QSocket

bool QIODevice::at ( Offset pos ) [virtual]

Virtual function that sets the I/O device position to pos. Returns TRUE if the position was successfully set — i.e. pos is within range and the seek worked out — otherwise returns FALSE. So a FALSE here means nope, couldn't get there 😭

  • See also: size()
  • Reimplemented in: QSocket

bool QIODevice::atEnd () const [virtual]

Virtual function that returns TRUE if the I/O device position is at the end of the input; otherwise returns FALSE.

  • Reimplemented in: QFile and QSocket

void QIODevice::close () [pure virtual]

Closes the I/O device.

This virtual function must be reimplemented by all subclasses. No skipping, bestie, it's mandatory 🙈

  • See also: open()
  • Example: grapher/grapher.cpp
  • Reimplemented in: QFile and QSocket

int QIODevice::flags () const

Returns the current I/O device flags setting.

Flags consists of mode flags and state flags.

  • See also: mode() and state()

void QIODevice::flush () [pure virtual]

Flushes an open I/O device.

This virtual function must be reimplemented by all subclasses. Again — required, not optional 💅

  • Reimplemented in: QFile and QSocket

int QIODevice::getch () [pure virtual]

Reads a single byte/character from the I/O device.

Returns the byte/character read, or -1 if the end of the I/O device has been reached.

This virtual function must be reimplemented by all subclasses.

  • See also: putch() and ungetch()
  • Reimplemented in: QFile and QSocket

bool QIODevice::isAsynchronous () const

Returns TRUE if the device is an asynchronous device; otherwise returns FALSE, i.e. if the device is a synchronous device.

This mode is currently not in use. (Lowkey just vibing there in the header file 😭)

  • See also: isSynchronous()

bool QIODevice::isBuffered () const

Returns TRUE if the I/O device is a buffered device; otherwise returns FALSE, i.e. the device is a raw device.

  • See also: isRaw()

bool QIODevice::isCombinedAccess () const

Returns TRUE if the I/O device is a combined access (both direct and sequential) device; otherwise returns FALSE.

This access method is currently not in use. (Another one just hanging out ✨)

bool QIODevice::isDirectAccess () const

Returns TRUE if the I/O device is a direct access device; otherwise returns FALSE, i.e. if the device is a sequential access device.

  • See also: isSequentialAccess()

bool QIODevice::isInactive () const

Returns TRUE if the I/O device state is 0, i.e. the device is not open; otherwise returns FALSE.

  • See also: isOpen()

bool QIODevice::isOpen () const

Returns TRUE if the I/O device has been opened; otherwise returns FALSE.

  • See also: isInactive()
  • Example: network/networkprotocol/nntp.cpp

bool QIODevice::isRaw () const

Returns TRUE if the device is a raw device; otherwise returns FALSE, i.e. if the device is a buffered device.

  • See also: isBuffered()

bool QIODevice::isReadWrite () const

Returns TRUE if the I/O device was opened using IO_ReadWrite mode; otherwise returns FALSE.

  • See also: isReadable() and isWritable()

bool QIODevice::isReadable () const

Returns TRUE if the I/O device was opened using IO_ReadOnly or IO_ReadWrite mode; otherwise returns FALSE.

  • See also: isWritable() and isReadWrite()

bool QIODevice::isSequentialAccess () const

Returns TRUE if the device is a sequential access device; otherwise returns FALSE, i.e. if the device is a direct access device.

Heads up bestie: operations involving size() and at(int) are not valid on sequential devices. Don't do it, it won't work 🚫
  • See also: isDirectAccess()

bool QIODevice::isSynchronous () const

Returns TRUE if the I/O device is a synchronous device; otherwise returns FALSE, i.e. the device is an asynchronous device.

  • See also: isAsynchronous()

bool QIODevice::isTranslated () const

Returns TRUE if the I/O device translates carriage-return and linefeed characters; otherwise returns FALSE.

A QFile is translated if it is opened with the IO_Translate mode flag. 📝

bool QIODevice::isWritable () const

Returns TRUE if the I/O device was opened using IO_WriteOnly or IO_ReadWrite mode; otherwise returns FALSE.

  • See also: isReadable() and isReadWrite()

int QIODevice::mode () const

okay so this one hands you back bits all OR'ed together that spell out the current operation mode. and where did those bits come from? they're literally the flags you passed to open() in the first place. 💅

the cast list is: IO_ReadOnly, IO_WriteOnly, IO_ReadWrite, IO_Append, IO_Truncate and IO_Translate. that's the whole lineup, no cap. ✨

bool QIODevice::open ( int mode ) [pure virtual]

opens the I/O device using the mode you give it. returns TRUE if the device opened successfully, otherwise returns FALSE. simple as. 🫶

the mode parameter has to be an OR'ed combination of the following flags:

<center>.nf
</center>
yeah bestie… that flags table did NOT survive whatever converted this page, it's giving broken HTML 😭. the flags that belong there are the ones mode() lists right above, since those are documented as the flags given to open().

this is a pure virtual function — it must be reimplemented by all subclasses. no skipping, it's mandatory, periodt.

See also close().

Example: grapher/grapher.cpp.

Reimplemented in QFile and QSocket.

int QIODevice::putch ( int ch ) [pure virtual]

writes the character ch to the I/O device. returns ch, or -1 if an error occurred. that's it, that's the whole vibe. 🌸

this is a pure virtual function — must be reimplemented by all subclasses, every single one.

See also getch() and ungetch().

Example: grapher/grapher.cpp.

Reimplemented in QFile and QSocket.

QByteArray QIODevice::readAll () [virtual]

a lil convenience function that returns all of the remaining data in the device. yes, all of it. the entire thing. iconic behaviour honestly. 🎀

Q_LONG QIODevice::readBlock ( char * data, Q_ULONG maxlen ) [pure virtual]

reads at most maxlen bytes from the I/O device into data, and returns the number of bytes actually read. ✨

it should return -1 if a fatal error occurs, and it should return 0 if there are no bytes to read. two very different moods, don't mix them up.

the device must be opened for reading, and data must not be 0.

this is a pure virtual function — must be reimplemented by all subclasses.

See also writeBlock(), isOpen(), and isReadable().

Example: distributor/distributor.ui.h.

Reimplemented in QSocket and QSocketDevice.

Q_LONG QIODevice::readLine ( char * data, Q_ULONG maxlen ) [virtual]

reads a line of text — or up to maxlen bytes if a newline isn't encountered — plus a terminating '\0' into data. and if there's a newline at the end of the line, it is not stripped. it stays. it's part of the package. 💅

returns the number of bytes read including the terminating '\0', or -1 if an error occurred.

this virtual function can be reimplemented much more efficiently by the most subclasses — so like, if you're a subclass, consider it, bestie. 🔥

See also readBlock() and QTextStream::readLine().

Reimplemented in QFile.

bool QIODevice::reset ()

sets the device index position to 0. back to the beginning, we're starting over, main character energy. 🌈

See also at().

void QIODevice::resetStatus ()

sets the I/O device status to IO_Ok. clean slate, healed, thriving. ✨

See also status().

void QIODevice::setFlags ( int flags ) [protected]

used by subclasses to set the device flags to the flags specified.

void QIODevice::setMode ( int mode ) [protected]

used by subclasses to set the device mode to the mode specified.

void QIODevice::setState ( int state ) [protected]

used by subclasses to set the device state to the state specified.

void QIODevice::setStatus ( int s ) [protected]

used by subclasses to set the device status (not state, ok? status, not state, they are different, do not confuse them 💀) to s.

void QIODevice::setType ( int type ) [protected]

used by subclasses to set the device type to the type specified.

Offset QIODevice::size () const [pure virtual]

a virtual function that returns the size of the I/O device. that's the whole job. 👑

See also at().

Reimplemented in QFile and QSocket.

int QIODevice::state () const

returns bits OR'ed together that specify the current state. ✨

the flags are: IO_Open.

subclasses may define additional flags — they're allowed to add their own, we love a flexible queen.

int QIODevice::status () const

returns the I/O device status.

the I/O device status returns an error code. so if open() returns FALSE, or readBlock() or writeBlock() return -1, you can call this function to find out why the operation failed. it's the gossip, it tells you what went wrong. 🔍

the status codes are:

<center>.nf
</center>
girl the status code table got eaten by the converter too 😭 that's genuinely so tragic. the only status name this page actually spells out anywhere is IO_Ok, over in resetStatus() above.

See also resetStatus().

int QIODevice::ungetch ( int ch ) [pure virtual]

puts the character ch back into the I/O device, and decrements the index position if it's not zero. ✨

this function is normally called to "undo" a getch() operation — like ctrl+z but for characters.

returns ch, or -1 if an error occurred.

this is a pure virtual function — must be reimplemented by all subclasses.

See also getch() and putch().

Reimplemented in QFile and QSocket.

Q_LONG QIODevice::writeBlock ( const char * data, Q_ULONG len ) [pure virtual]

writes len bytes from data to the I/O device, and returns the number of bytes actually written. 💅

this function should return -1 if a fatal error occurs.

this is a pure virtual function — must be reimplemented by all subclasses.

See also readBlock().

Example: distributor/distributor.ui.h.

Reimplemented in QBuffer, QSocket, and QSocketDevice.

Q_LONG QIODevice::writeBlock ( const QByteArray & data )

this is an overloaded member function, provided for convenience. it behaves essentially like the above function. 🫶

this convenience function is the same as calling:

writeBlock( data.data(), data.size() )

💖 SEE ALSO 💖

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement. 📜

✨ AUTHOR ✨

Generated automatically from the source code. (the source code wrote this, not a human, which honestly? slay. 🤖💅)

🐛 BUGS 🐛

if you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. good bug reports help us to help you. thank you. 🫶 (fr fr, a good bug report is a gift)

the definitive Qt documentation is provided in HTML format; it's located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. this man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech. so like, it's a nice-to-have, not the moment. 🙈

if you find errors in this manual page, please report them to qt-bugs@trolltech.com. please include the name of the manual page (qiodevice.3qt) and the Qt version (3.3.8). 🌸

okay that's the whole page bestie, we did it, we ate and left absolutely no crumbs 🍓💜 shoutout to Trolltech AS, who shipped this on 2 February 2007, and to QIODevice(3qt) itself — a real one, an icon, the blueprint. go close your file descriptors, hydrate, and stream responsibly. byeeee ✨🦋

📦 where this page comes from