Do not load plugin from the $PWD
[mirror/qt/qtbase.git] / src / corelib / io / qiodevice.cpp
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtCore module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL21$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** $QT_END_LICENSE$
31 **
32 ****************************************************************************/
33
34 //#define QIODEVICE_DEBUG
35
36 #include "qbytearray.h"
37 #include "qdebug.h"
38 #include "qiodevice_p.h"
39 #include "qfile.h"
40 #include "qstringlist.h"
41 #include "qdir.h"
42
43 #include <algorithm>
44
45 #ifdef QIODEVICE_DEBUG
46 #  include <ctype.h>
47 #endif
48
49 QT_BEGIN_NAMESPACE
50
51 #ifdef QIODEVICE_DEBUG
52 void debugBinaryString(const QByteArray &input)
53 {
54     QByteArray tmp;
55     int startOffset = 0;
56     for (int i = 0; i < input.size(); ++i) {
57         tmp += input[i];
58
59         if ((i % 16) == 15 || i == (input.size() - 1)) {
60             printf("\n%15d:", startOffset);
61             startOffset += tmp.size();
62
63             for (int j = 0; j < tmp.size(); ++j)
64                 printf(" %02x", int(uchar(tmp[j])));
65             for (int j = tmp.size(); j < 16 + 1; ++j)
66                 printf("   ");
67             for (int j = 0; j < tmp.size(); ++j)
68                 printf("%c", isprint(int(uchar(tmp[j]))) ? tmp[j] : '.');
69             tmp.clear();
70         }
71     }
72     printf("\n\n");
73 }
74
75 void debugBinaryString(const char *data, qint64 maxlen)
76 {
77     debugBinaryString(QByteArray(data, maxlen));
78 }
79 #endif
80
81 #define Q_VOID
82
83 static void checkWarnMessage(const QIODevice *device, const char *function, const char *what)
84 {
85     QDebug d = qWarning();
86     d.noquote();
87     d.nospace();
88     d << "QIODevice::" << function;
89 #ifndef QT_NO_QOBJECT
90     d << " (" << device->metaObject()->className();
91     if (!device->objectName().isEmpty())
92         d << ", \"" << device->objectName() << '"';
93     if (const QFile *f = qobject_cast<const QFile *>(device))
94         d << ", \"" << QDir::toNativeSeparators(f->fileName()) << '"';
95     d << ')';
96 #else
97     Q_UNUSED(device)
98 #endif // !QT_NO_QOBJECT
99     d << ": " << what;
100 }
101
102 #define CHECK_MAXLEN(function, returnType) \
103     do { \
104         if (maxSize < 0) { \
105             checkWarnMessage(this, #function, "Called with maxSize < 0"); \
106             return returnType; \
107         } \
108     } while (0)
109
110 #define CHECK_WRITABLE(function, returnType) \
111    do { \
112        if ((d->openMode & WriteOnly) == 0) { \
113            if (d->openMode == NotOpen) { \
114                checkWarnMessage(this, #function, "device not open"); \
115                return returnType; \
116            } \
117            checkWarnMessage(this, #function, "ReadOnly device"); \
118            return returnType; \
119        } \
120    } while (0)
121
122 #define CHECK_READABLE(function, returnType) \
123    do { \
124        if ((d->openMode & ReadOnly) == 0) { \
125            if (d->openMode == NotOpen) { \
126                checkWarnMessage(this, #function, "device not open"); \
127                return returnType; \
128            } \
129            checkWarnMessage(this, #function, "WriteOnly device"); \
130            return returnType; \
131        } \
132    } while (0)
133
134 /*!
135     \internal
136  */
137 QIODevicePrivate::QIODevicePrivate()
138     : openMode(QIODevice::NotOpen), buffer(QIODEVICE_BUFFERSIZE),
139       pos(0), devicePos(0)
140        , baseReadLineDataCalled(false)
141        , firstRead(true)
142        , accessMode(Unset)
143 #ifdef QT_NO_QOBJECT
144        , q_ptr(0)
145 #endif
146 {
147 }
148
149 /*!
150     \internal
151  */
152 QIODevicePrivate::~QIODevicePrivate()
153 {
154 }
155
156 /*!
157     \class QIODevice
158     \inmodule QtCore
159     \reentrant
160
161     \brief The QIODevice class is the base interface class of all I/O
162     devices in Qt.
163
164     \ingroup io
165
166     QIODevice provides both a common implementation and an abstract
167     interface for devices that support reading and writing of blocks
168     of data, such as QFile, QBuffer and QTcpSocket. QIODevice is
169     abstract and can not be instantiated, but it is common to use the
170     interface it defines to provide device-independent I/O features.
171     For example, Qt's XML classes operate on a QIODevice pointer,
172     allowing them to be used with various devices (such as files and
173     buffers).
174
175     Before accessing the device, open() must be called to set the
176     correct OpenMode (such as ReadOnly or ReadWrite). You can then
177     write to the device with write() or putChar(), and read by calling
178     either read(), readLine(), or readAll(). Call close() when you are
179     done with the device.
180
181     QIODevice distinguishes between two types of devices:
182     random-access devices and sequential devices.
183
184     \list
185     \li Random-access devices support seeking to arbitrary
186     positions using seek(). The current position in the file is
187     available by calling pos(). QFile and QBuffer are examples of
188     random-access devices.
189
190     \li Sequential devices don't support seeking to arbitrary
191     positions. The data must be read in one pass. The functions
192     pos() and size() don't work for sequential devices.
193     QTcpSocket and QProcess are examples of sequential devices.
194     \endlist
195
196     You can use isSequential() to determine the type of device.
197
198     QIODevice emits readyRead() when new data is available for
199     reading; for example, if new data has arrived on the network or if
200     additional data is appended to a file that you are reading
201     from. You can call bytesAvailable() to determine the number of
202     bytes that are currently available for reading. It's common to use
203     bytesAvailable() together with the readyRead() signal when
204     programming with asynchronous devices such as QTcpSocket, where
205     fragments of data can arrive at arbitrary points in
206     time. QIODevice emits the bytesWritten() signal every time a
207     payload of data has been written to the device. Use bytesToWrite()
208     to determine the current amount of data waiting to be written.
209
210     Certain subclasses of QIODevice, such as QTcpSocket and QProcess,
211     are asynchronous. This means that I/O functions such as write()
212     or read() always return immediately, while communication with the
213     device itself may happen when control goes back to the event loop.
214     QIODevice provides functions that allow you to force these
215     operations to be performed immediately, while blocking the
216     calling thread and without entering the event loop. This allows
217     QIODevice subclasses to be used without an event loop, or in
218     a separate thread:
219
220     \list
221     \li waitForReadyRead() - This function suspends operation in the
222     calling thread until new data is available for reading.
223
224     \li waitForBytesWritten() - This function suspends operation in the
225     calling thread until one payload of data has been written to the
226     device.
227
228     \li waitFor....() - Subclasses of QIODevice implement blocking
229     functions for device-specific operations. For example, QProcess
230     has a function called \l {QProcess::}{waitForStarted()} which suspends operation in
231     the calling thread until the process has started.
232     \endlist
233
234     Calling these functions from the main, GUI thread, may cause your
235     user interface to freeze. Example:
236
237     \snippet code/src_corelib_io_qiodevice.cpp 0
238
239     By subclassing QIODevice, you can provide the same interface to
240     your own I/O devices. Subclasses of QIODevice are only required to
241     implement the protected readData() and writeData() functions.
242     QIODevice uses these functions to implement all its convenience
243     functions, such as getChar(), readLine() and write(). QIODevice
244     also handles access control for you, so you can safely assume that
245     the device is opened in write mode if writeData() is called.
246
247     Some subclasses, such as QFile and QTcpSocket, are implemented
248     using a memory buffer for intermediate storing of data. This
249     reduces the number of required device accessing calls, which are
250     often very slow. Buffering makes functions like getChar() and
251     putChar() fast, as they can operate on the memory buffer instead
252     of directly on the device itself. Certain I/O operations, however,
253     don't work well with a buffer. For example, if several users open
254     the same device and read it character by character, they may end
255     up reading the same data when they meant to read a separate chunk
256     each. For this reason, QIODevice allows you to bypass any
257     buffering by passing the Unbuffered flag to open(). When
258     subclassing QIODevice, remember to bypass any buffer you may use
259     when the device is open in Unbuffered mode.
260
261     \sa QBuffer, QFile, QTcpSocket
262 */
263
264 /*!
265     \enum QIODevice::OpenModeFlag
266
267     This enum is used with open() to describe the mode in which a device
268     is opened. It is also returned by openMode().
269
270     \value NotOpen   The device is not open.
271     \value ReadOnly  The device is open for reading.
272     \value WriteOnly The device is open for writing. Note that this mode implies
273                      Truncate.
274     \value ReadWrite The device is open for reading and writing.
275     \value Append    The device is opened in append mode so that all data is
276                      written to the end of the file.
277     \value Truncate  If possible, the device is truncated before it is opened.
278                      All earlier contents of the device are lost.
279     \value Text      When reading, the end-of-line terminators are
280                      translated to '\\n'. When writing, the end-of-line
281                      terminators are translated to the local encoding, for
282                      example '\\r\\n' for Win32.
283     \value Unbuffered Any buffer in the device is bypassed.
284
285     Certain flags, such as \c Unbuffered and \c Truncate, are
286     meaningless when used with some subclasses. Some of these
287     restrictions are implied by the type of device that is represented
288     by a subclass. In other cases, the restriction may be due to the
289     implementation, or may be imposed by the underlying platform; for
290     example, QTcpSocket does not support \c Unbuffered mode, and
291     limitations in the native API prevent QFile from supporting \c
292     Unbuffered on Windows.
293 */
294
295 /*!     \fn QIODevice::bytesWritten(qint64 bytes)
296
297     This signal is emitted every time a payload of data has been
298     written to the device. The \a bytes argument is set to the number
299     of bytes that were written in this payload.
300
301     bytesWritten() is not emitted recursively; if you reenter the event loop
302     or call waitForBytesWritten() inside a slot connected to the
303     bytesWritten() signal, the signal will not be reemitted (although
304     waitForBytesWritten() may still return true).
305
306     \sa readyRead()
307 */
308
309 /*!
310     \fn QIODevice::readyRead()
311
312     This signal is emitted once every time new data is available for
313     reading from the device. It will only be emitted again once new
314     data is available, such as when a new payload of network data has
315     arrived on your network socket, or when a new block of data has
316     been appended to your device.
317
318     readyRead() is not emitted recursively; if you reenter the event loop or
319     call waitForReadyRead() inside a slot connected to the readyRead() signal,
320     the signal will not be reemitted (although waitForReadyRead() may still
321     return true).
322
323     Note for developers implementing classes derived from QIODevice:
324     you should always emit readyRead() when new data has arrived (do not
325     emit it only because there's data still to be read in your
326     buffers). Do not emit readyRead() in other conditions.
327
328     \sa bytesWritten()
329 */
330
331 /*! \fn QIODevice::aboutToClose()
332
333     This signal is emitted when the device is about to close. Connect
334     this signal if you have operations that need to be performed
335     before the device closes (e.g., if you have data in a separate
336     buffer that needs to be written to the device).
337 */
338
339 /*!
340     \fn QIODevice::readChannelFinished()
341     \since 4.4
342
343     This signal is emitted when the input (reading) stream is closed
344     in this device. It is emitted as soon as the closing is detected,
345     which means that there might still be data available for reading
346     with read().
347
348     \sa atEnd(), read()
349 */
350
351 #ifdef QT_NO_QOBJECT
352 QIODevice::QIODevice()
353     : d_ptr(new QIODevicePrivate)
354 {
355     d_ptr->q_ptr = this;
356 }
357
358 /*!
359     \internal
360 */
361 QIODevice::QIODevice(QIODevicePrivate &dd)
362     : d_ptr(&dd)
363 {
364     d_ptr->q_ptr = this;
365 }
366 #else
367
368 /*!
369     Constructs a QIODevice object.
370 */
371
372 QIODevice::QIODevice()
373     : QObject(*new QIODevicePrivate, 0)
374 {
375 #if defined QIODEVICE_DEBUG
376     QFile *file = qobject_cast<QFile *>(this);
377     printf("%p QIODevice::QIODevice(\"%s\") %s\n", this, metaObject()->className(),
378            qPrintable(file ? file->fileName() : QString()));
379 #endif
380 }
381
382 /*!
383     Constructs a QIODevice object with the given \a parent.
384 */
385
386 QIODevice::QIODevice(QObject *parent)
387     : QObject(*new QIODevicePrivate, parent)
388 {
389 #if defined QIODEVICE_DEBUG
390     printf("%p QIODevice::QIODevice(%p \"%s\")\n", this, parent, metaObject()->className());
391 #endif
392 }
393
394 /*!
395     \internal
396 */
397 QIODevice::QIODevice(QIODevicePrivate &dd, QObject *parent)
398     : QObject(dd, parent)
399 {
400 }
401 #endif
402
403
404 /*!
405   The destructor is virtual, and QIODevice is an abstract base
406   class. This destructor does not call close(), but the subclass
407   destructor might. If you are in doubt, call close() before
408   destroying the QIODevice.
409 */
410 QIODevice::~QIODevice()
411 {
412 #if defined QIODEVICE_DEBUG
413     printf("%p QIODevice::~QIODevice()\n", this);
414 #endif
415 }
416
417 /*!
418     Returns \c true if this device is sequential; otherwise returns
419     false.
420
421     Sequential devices, as opposed to a random-access devices, have no
422     concept of a start, an end, a size, or a current position, and they
423     do not support seeking. You can only read from the device when it
424     reports that data is available. The most common example of a
425     sequential device is a network socket. On Unix, special files such
426     as /dev/zero and fifo pipes are sequential.
427
428     Regular files, on the other hand, do support random access. They
429     have both a size and a current position, and they also support
430     seeking backwards and forwards in the data stream. Regular files
431     are non-sequential.
432
433     \sa bytesAvailable()
434 */
435 bool QIODevice::isSequential() const
436 {
437     return false;
438 }
439
440 /*!
441     Returns the mode in which the device has been opened;
442     i.e. ReadOnly or WriteOnly.
443
444     \sa OpenMode
445 */
446 QIODevice::OpenMode QIODevice::openMode() const
447 {
448     return d_func()->openMode;
449 }
450
451 /*!
452     Sets the OpenMode of the device to \a openMode. Call this
453     function to set the open mode if the flags change after the device
454     has been opened.
455
456     \sa openMode(), OpenMode
457 */
458 void QIODevice::setOpenMode(OpenMode openMode)
459 {
460     Q_D(QIODevice);
461 #if defined QIODEVICE_DEBUG
462     printf("%p QIODevice::setOpenMode(0x%x)\n", this, int(openMode));
463 #endif
464     d->openMode = openMode;
465     d->accessMode = QIODevicePrivate::Unset;
466     d->firstRead = true;
467     if (!isReadable())
468         d->buffer.clear();
469 }
470
471 /*!
472     If \a enabled is true, this function sets the \l Text flag on the device;
473     otherwise the \l Text flag is removed. This feature is useful for classes
474     that provide custom end-of-line handling on a QIODevice.
475
476     The IO device should be opened before calling this function.
477
478     \sa open(), setOpenMode()
479  */
480 void QIODevice::setTextModeEnabled(bool enabled)
481 {
482     Q_D(QIODevice);
483     if (!isOpen()) {
484         checkWarnMessage(this, "setTextModeEnabled", "The device is not open");
485         return;
486     }
487     if (enabled)
488         d->openMode |= Text;
489     else
490         d->openMode &= ~Text;
491 }
492
493 /*!
494     Returns \c true if the \l Text flag is enabled; otherwise returns \c false.
495
496     \sa setTextModeEnabled()
497 */
498 bool QIODevice::isTextModeEnabled() const
499 {
500     return d_func()->openMode & Text;
501 }
502
503 /*!
504     Returns \c true if the device is open; otherwise returns \c false. A
505     device is open if it can be read from and/or written to. By
506     default, this function returns \c false if openMode() returns
507     \c NotOpen.
508
509     \sa openMode(), OpenMode
510 */
511 bool QIODevice::isOpen() const
512 {
513     return d_func()->openMode != NotOpen;
514 }
515
516 /*!
517     Returns \c true if data can be read from the device; otherwise returns
518     false. Use bytesAvailable() to determine how many bytes can be read.
519
520     This is a convenience function which checks if the OpenMode of the
521     device contains the ReadOnly flag.
522
523     \sa openMode(), OpenMode
524 */
525 bool QIODevice::isReadable() const
526 {
527     return (openMode() & ReadOnly) != 0;
528 }
529
530 /*!
531     Returns \c true if data can be written to the device; otherwise returns
532     false.
533
534     This is a convenience function which checks if the OpenMode of the
535     device contains the WriteOnly flag.
536
537     \sa openMode(), OpenMode
538 */
539 bool QIODevice::isWritable() const
540 {
541     return (openMode() & WriteOnly) != 0;
542 }
543
544 /*!
545     Opens the device and sets its OpenMode to \a mode. Returns \c true if successful;
546     otherwise returns \c false. This function should be called from any
547     reimplementations of open() or other functions that open the device.
548
549     \sa openMode(), OpenMode
550 */
551 bool QIODevice::open(OpenMode mode)
552 {
553     Q_D(QIODevice);
554     d->openMode = mode;
555     d->pos = (mode & Append) ? size() : qint64(0);
556     d->buffer.clear();
557     d->accessMode = QIODevicePrivate::Unset;
558     d->firstRead = true;
559 #if defined QIODEVICE_DEBUG
560     printf("%p QIODevice::open(0x%x)\n", this, quint32(mode));
561 #endif
562     return true;
563 }
564
565 /*!
566     First emits aboutToClose(), then closes the device and sets its
567     OpenMode to NotOpen. The error string is also reset.
568
569     \sa setOpenMode(), OpenMode
570 */
571 void QIODevice::close()
572 {
573     Q_D(QIODevice);
574     if (d->openMode == NotOpen)
575         return;
576
577 #if defined QIODEVICE_DEBUG
578     printf("%p QIODevice::close()\n", this);
579 #endif
580
581 #ifndef QT_NO_QOBJECT
582     emit aboutToClose();
583 #endif
584     d->openMode = NotOpen;
585     d->errorString.clear();
586     d->pos = 0;
587     d->buffer.clear();
588     d->firstRead = true;
589 }
590
591 /*!
592     For random-access devices, this function returns the position that
593     data is written to or read from. For sequential devices or closed
594     devices, where there is no concept of a "current position", 0 is
595     returned.
596
597     The current read/write position of the device is maintained internally by
598     QIODevice, so reimplementing this function is not necessary. When
599     subclassing QIODevice, use QIODevice::seek() to notify QIODevice about
600     changes in the device position.
601
602     \sa isSequential(), seek()
603 */
604 qint64 QIODevice::pos() const
605 {
606     Q_D(const QIODevice);
607 #if defined QIODEVICE_DEBUG
608     printf("%p QIODevice::pos() == %lld\n", this, d->pos);
609 #endif
610     return d->pos;
611 }
612
613 /*!
614     For open random-access devices, this function returns the size of the
615     device. For open sequential devices, bytesAvailable() is returned.
616
617     If the device is closed, the size returned will not reflect the actual
618     size of the device.
619
620     \sa isSequential(), pos()
621 */
622 qint64 QIODevice::size() const
623 {
624     return d_func()->isSequential() ?  bytesAvailable() : qint64(0);
625 }
626
627 /*!
628     For random-access devices, this function sets the current position
629     to \a pos, returning true on success, or false if an error occurred.
630     For sequential devices, the default behavior is to produce a warning
631     and return false.
632
633     When subclassing QIODevice, you must call QIODevice::seek() at the
634     start of your function to ensure integrity with QIODevice's
635     built-in buffer.
636
637     \sa pos(), isSequential()
638 */
639 bool QIODevice::seek(qint64 pos)
640 {
641     Q_D(QIODevice);
642     if (d->isSequential()) {
643         checkWarnMessage(this, "seek", "Cannot call seek on a sequential device");
644         return false;
645     }
646     if (d->openMode == NotOpen) {
647         checkWarnMessage(this, "seek", "The device is not open");
648         return false;
649     }
650     if (pos < 0) {
651         qWarning("QIODevice::seek: Invalid pos: %lld", pos);
652         return false;
653     }
654
655 #if defined QIODEVICE_DEBUG
656     printf("%p QIODevice::seek(%lld), before: d->pos = %lld, d->buffer.size() = %lld\n",
657            this, pos, d->pos, d->buffer.size());
658 #endif
659
660     qint64 offset = pos - d->pos;
661     d->pos = pos;
662     d->devicePos = pos;
663
664     if (offset < 0 || offset >= d->buffer.size())
665         // When seeking backwards, an operation that is only allowed for
666         // random-access devices, the buffer is cleared. The next read
667         // operation will then refill the buffer. We can optimize this, if we
668         // find that seeking backwards becomes a significant performance hit.
669         d->buffer.clear();
670     else if (!d->buffer.isEmpty())
671         d->buffer.skip(offset);
672
673 #if defined QIODEVICE_DEBUG
674     printf("%p \tafter: d->pos == %lld, d->buffer.size() == %lld\n", this, d->pos,
675            d->buffer.size());
676 #endif
677     return true;
678 }
679
680 /*!
681     Returns \c true if the current read and write position is at the end
682     of the device (i.e. there is no more data available for reading on
683     the device); otherwise returns \c false.
684
685     For some devices, atEnd() can return true even though there is more data
686     to read. This special case only applies to devices that generate data in
687     direct response to you calling read() (e.g., \c /dev or \c /proc files on
688     Unix and OS X, or console input / \c stdin on all platforms).
689
690     \sa bytesAvailable(), read(), isSequential()
691 */
692 bool QIODevice::atEnd() const
693 {
694     Q_D(const QIODevice);
695 #if defined QIODEVICE_DEBUG
696     printf("%p QIODevice::atEnd() returns %s, d->openMode == %d, d->pos == %lld\n", this,
697            (d->openMode == NotOpen || d->pos == size()) ? "true" : "false", int(d->openMode),
698            d->pos);
699 #endif
700     return d->openMode == NotOpen || (d->buffer.isEmpty() && bytesAvailable() == 0);
701 }
702
703 /*!
704     Seeks to the start of input for random-access devices. Returns
705     true on success; otherwise returns \c false (for example, if the
706     device is not open).
707
708     Note that when using a QTextStream on a QFile, calling reset() on
709     the QFile will not have the expected result because QTextStream
710     buffers the file. Use the QTextStream::seek() function instead.
711
712     \sa seek()
713 */
714 bool QIODevice::reset()
715 {
716 #if defined QIODEVICE_DEBUG
717     printf("%p QIODevice::reset()\n", this);
718 #endif
719     return seek(0);
720 }
721
722 /*!
723     Returns the number of bytes that are available for reading. This
724     function is commonly used with sequential devices to determine the
725     number of bytes to allocate in a buffer before reading.
726
727     Subclasses that reimplement this function must call the base
728     implementation in order to include the size of the buffer of QIODevice. Example:
729
730     \snippet code/src_corelib_io_qiodevice.cpp 1
731
732     \sa bytesToWrite(), readyRead(), isSequential()
733 */
734 qint64 QIODevice::bytesAvailable() const
735 {
736     Q_D(const QIODevice);
737     if (!d->isSequential())
738         return qMax(size() - d->pos, qint64(0));
739     return d->buffer.size();
740 }
741
742 /*!  For buffered devices, this function returns the number of bytes
743     waiting to be written. For devices with no buffer, this function
744     returns 0.
745
746     \sa bytesAvailable(), bytesWritten(), isSequential()
747 */
748 qint64 QIODevice::bytesToWrite() const
749 {
750     return qint64(0);
751 }
752
753 /*!
754     Reads at most \a maxSize bytes from the device into \a data, and
755     returns the number of bytes read. If an error occurs, such as when
756     attempting to read from a device opened in WriteOnly mode, this
757     function returns -1.
758
759     0 is returned when no more data is available for reading. However,
760     reading past the end of the stream is considered an error, so this
761     function returns -1 in those cases (that is, reading on a closed
762     socket or after a process has died).
763
764     \sa readData(), readLine(), write()
765 */
766 qint64 QIODevice::read(char *data, qint64 maxSize)
767 {
768     Q_D(QIODevice);
769
770 #if defined QIODEVICE_DEBUG
771     printf("%p QIODevice::read(%p, %lld), d->pos = %lld, d->buffer.size() = %lld\n",
772            this, data, maxSize, d->pos, d->buffer.size());
773 #endif
774
775     const bool sequential = d->isSequential();
776
777     // Short circuit for getChar()
778     if (maxSize == 1) {
779         int chint;
780         while ((chint = d->buffer.getChar()) != -1) {
781             if (!sequential)
782                 ++d->pos;
783
784             char c = char(uchar(chint));
785             if (c == '\r' && (d->openMode & Text))
786                 continue;
787             *data = c;
788 #if defined QIODEVICE_DEBUG
789             printf("%p \tread 0x%hhx (%c) returning 1 (shortcut)\n", this,
790                    int(c), isprint(c) ? c : '?');
791 #endif
792             if (d->buffer.isEmpty())
793                 readData(data, 0);
794             return qint64(1);
795         }
796     }
797
798     CHECK_MAXLEN(read, qint64(-1));
799     qint64 readSoFar = 0;
800     bool madeBufferReadsOnly = true;
801     bool deviceAtEof = false;
802     char *readPtr = data;
803     forever {
804         // Try reading from the buffer.
805         qint64 bufferReadChunkSize = d->buffer.read(data, maxSize);
806         if (bufferReadChunkSize > 0) {
807             if (!sequential)
808                 d->pos += bufferReadChunkSize;
809             readSoFar += bufferReadChunkSize;
810             data += bufferReadChunkSize;
811             maxSize -= bufferReadChunkSize;
812 #if defined QIODEVICE_DEBUG
813             printf("%p \treading %lld bytes from buffer into position %lld\n", this,
814                    bufferReadChunkSize, readSoFar - bufferReadChunkSize);
815 #endif
816         } else {
817             if (d->firstRead) {
818                 // this is the first time the file has been read, check it's valid and set up pos pointers
819                 // for fast pos updates.
820                 CHECK_READABLE(read, qint64(-1));
821                 d->firstRead = false;
822             }
823         }
824
825         if (maxSize > 0 && !deviceAtEof) {
826             qint64 readFromDevice = 0;
827             // Make sure the device is positioned correctly.
828             if (sequential || d->pos == d->devicePos || seek(d->pos)) {
829                 madeBufferReadsOnly = false; // fix readData attempt
830                 if (maxSize >= QIODEVICE_BUFFERSIZE || (d->openMode & Unbuffered)) {
831                     // Read big chunk directly to output buffer
832                     readFromDevice = readData(data, maxSize);
833                     deviceAtEof = (readFromDevice != maxSize);
834 #if defined QIODEVICE_DEBUG
835                     printf("%p \treading %lld bytes from device (total %lld)\n", this,
836                            readFromDevice, readSoFar);
837 #endif
838                     if (readFromDevice > 0) {
839                         readSoFar += readFromDevice;
840                         data += readFromDevice;
841                         maxSize -= readFromDevice;
842                         if (!sequential) {
843                             d->pos += readFromDevice;
844                             d->devicePos += readFromDevice;
845                         }
846                     }
847                 } else {
848                     const qint64 bytesToBuffer = QIODEVICE_BUFFERSIZE;
849                     // Try to fill QIODevice buffer by single read
850                     readFromDevice = readData(d->buffer.reserve(bytesToBuffer), bytesToBuffer);
851                     deviceAtEof = (readFromDevice != bytesToBuffer);
852                     d->buffer.chop(bytesToBuffer - qMax(Q_INT64_C(0), readFromDevice));
853                     if (readFromDevice > 0) {
854                         if (!sequential)
855                             d->devicePos += readFromDevice;
856 #if defined QIODEVICE_DEBUG
857                         printf("%p \treading %lld from device into buffer\n", this,
858                                readFromDevice);
859 #endif
860                         continue;
861                     }
862                 }
863             } else {
864                 readFromDevice = -1;
865             }
866
867             if (readFromDevice < 0 && readSoFar == 0) {
868                 // error and we haven't read anything: return immediately
869                 return qint64(-1);
870             }
871         }
872
873         if ((d->openMode & Text) && readPtr < data) {
874             const char *endPtr = data;
875
876             // optimization to avoid initial self-assignment
877             while (*readPtr != '\r') {
878                 if (++readPtr == endPtr)
879                     break;
880             }
881
882             char *writePtr = readPtr;
883
884             while (readPtr < endPtr) {
885                 char ch = *readPtr++;
886                 if (ch != '\r')
887                     *writePtr++ = ch;
888                 else {
889                     --readSoFar;
890                     --data;
891                     ++maxSize;
892                 }
893             }
894
895             // Make sure we get more data if there is room for more. This
896             // is very important for when someone seeks to the start of a
897             // '\r\n' and reads one character - they should get the '\n'.
898             readPtr = data;
899             continue;
900         }
901
902         break;
903     }
904
905 #if defined QIODEVICE_DEBUG
906     printf("%p \treturning %lld, d->pos == %lld, d->buffer.size() == %lld\n", this,
907            readSoFar, d->pos, d->buffer.size());
908     debugBinaryString(data - readSoFar, readSoFar);
909 #endif
910
911     if (madeBufferReadsOnly && d->buffer.isEmpty()) {
912         d->buffer.clear();
913         readData(data, 0);
914     }
915
916     return readSoFar;
917 }
918
919 /*!
920     \overload
921
922     Reads at most \a maxSize bytes from the device, and returns the
923     data read as a QByteArray.
924
925     This function has no way of reporting errors; returning an empty
926     QByteArray can mean either that no data was currently available
927     for reading, or that an error occurred.
928 */
929
930 QByteArray QIODevice::read(qint64 maxSize)
931 {
932     Q_D(QIODevice);
933     QByteArray result;
934
935     CHECK_MAXLEN(read, result);
936
937 #if defined QIODEVICE_DEBUG
938     printf("%p QIODevice::read(%lld), d->pos = %lld, d->buffer.size() = %lld\n",
939            this, maxSize, d->pos, d->buffer.size());
940 #else
941     Q_UNUSED(d);
942 #endif
943
944     if (quint64(maxSize) >= QByteArray::MaxSize) {
945         checkWarnMessage(this, "read", "maxSize argument exceeds QByteArray size limit");
946         maxSize = QByteArray::MaxSize - 1;
947     }
948
949     qint64 readBytes = 0;
950     if (maxSize) {
951         result.resize(int(maxSize));
952         if (!result.size()) {
953             // If resize fails, read incrementally.
954             qint64 readResult;
955             do {
956                 result.resize(int(qMin(maxSize, result.size() + QIODEVICE_BUFFERSIZE)));
957                 readResult = read(result.data() + readBytes, result.size() - readBytes);
958                 if (readResult > 0 || readBytes == 0)
959                     readBytes += readResult;
960             } while (readResult == QIODEVICE_BUFFERSIZE);
961         } else {
962             readBytes = read(result.data(), result.size());
963         }
964     }
965
966     if (readBytes <= 0)
967         result.clear();
968     else
969         result.resize(int(readBytes));
970
971     return result;
972 }
973
974 /*!
975     \overload
976
977     Reads all available data from the device, and returns it as a
978     byte array.
979
980     This function has no way of reporting errors; returning an empty
981     QByteArray can mean either that no data was currently available
982     for reading, or that an error occurred.
983 */
984 QByteArray QIODevice::readAll()
985 {
986     Q_D(QIODevice);
987 #if defined QIODEVICE_DEBUG
988     printf("%p QIODevice::readAll(), d->pos = %lld, d->buffer.size() = %lld\n",
989            this, d->pos, d->buffer.size());
990 #endif
991
992     QByteArray result;
993     qint64 readBytes = 0;
994     const bool sequential = d->isSequential();
995
996     // flush internal read buffer
997     if (!(d->openMode & Text) && !d->buffer.isEmpty()) {
998         if (quint64(d->buffer.size()) >= QByteArray::MaxSize)
999             return QByteArray();
1000         result = d->buffer.readAll();
1001         readBytes = result.size();
1002         if (!sequential)
1003             d->pos += readBytes;
1004     }
1005
1006     qint64 theSize;
1007     if (sequential || (theSize = size()) == 0) {
1008         // Size is unknown, read incrementally.
1009         qint64 readResult;
1010         do {
1011             if (quint64(readBytes) + QIODEVICE_BUFFERSIZE > QByteArray::MaxSize) {
1012                 // If resize would fail, don't read more, return what we have.
1013                 break;
1014             }
1015             result.resize(readBytes + QIODEVICE_BUFFERSIZE);
1016             readResult = read(result.data() + readBytes, QIODEVICE_BUFFERSIZE);
1017             if (readResult > 0 || readBytes == 0)
1018                 readBytes += readResult;
1019         } while (readResult > 0);
1020     } else {
1021         // Read it all in one go.
1022         // If resize fails, don't read anything.
1023         if (quint64(readBytes + theSize - d->pos) > QByteArray::MaxSize)
1024             return QByteArray();
1025         result.resize(int(readBytes + theSize - d->pos));
1026         readBytes += read(result.data() + readBytes, result.size() - readBytes);
1027     }
1028
1029     if (readBytes <= 0)
1030         result.clear();
1031     else
1032         result.resize(int(readBytes));
1033
1034     return result;
1035 }
1036
1037 /*!
1038     This function reads a line of ASCII characters from the device, up
1039     to a maximum of \a maxSize - 1 bytes, stores the characters in \a
1040     data, and returns the number of bytes read. If a line could not be
1041     read but no error ocurred, this function returns 0. If an error
1042     occurs, this function returns the length of what could be read, or
1043     -1 if nothing was read.
1044
1045     A terminating '\\0' byte is always appended to \a data, so \a
1046     maxSize must be larger than 1.
1047
1048     Data is read until either of the following conditions are met:
1049
1050     \list
1051     \li The first '\\n' character is read.
1052     \li \a maxSize - 1 bytes are read.
1053     \li The end of the device data is detected.
1054     \endlist
1055
1056     For example, the following code reads a line of characters from a
1057     file:
1058
1059     \snippet code/src_corelib_io_qiodevice.cpp 2
1060
1061     The newline character ('\\n') is included in the buffer. If a
1062     newline is not encountered before maxSize - 1 bytes are read, a
1063     newline will not be inserted into the buffer. On windows newline
1064     characters are replaced with '\\n'.
1065
1066     This function calls readLineData(), which is implemented using
1067     repeated calls to getChar(). You can provide a more efficient
1068     implementation by reimplementing readLineData() in your own
1069     subclass.
1070
1071     \sa getChar(), read(), write()
1072 */
1073 qint64 QIODevice::readLine(char *data, qint64 maxSize)
1074 {
1075     Q_D(QIODevice);
1076     if (maxSize < 2) {
1077         checkWarnMessage(this, "readLine", "Called with maxSize < 2");
1078         return qint64(-1);
1079     }
1080
1081 #if defined QIODEVICE_DEBUG
1082     printf("%p QIODevice::readLine(%p, %lld), d->pos = %lld, d->buffer.size() = %lld\n",
1083            this, data, maxSize, d->pos, d->buffer.size());
1084 #endif
1085
1086     // Leave room for a '\0'
1087     --maxSize;
1088
1089     const bool sequential = d->isSequential();
1090
1091     qint64 readSoFar = 0;
1092     if (!d->buffer.isEmpty()) {
1093         readSoFar = d->buffer.readLine(data, maxSize);
1094         if (d->buffer.isEmpty())
1095             readData(data,0);
1096         if (!sequential)
1097             d->pos += readSoFar;
1098 #if defined QIODEVICE_DEBUG
1099         printf("%p \tread from buffer: %lld bytes, last character read: %hhx\n", this,
1100                readSoFar, data[readSoFar - 1]);
1101         if (readSoFar)
1102             debugBinaryString(data, int(readSoFar));
1103 #endif
1104         if (readSoFar && data[readSoFar - 1] == '\n') {
1105             if (d->openMode & Text) {
1106                 // QRingBuffer::readLine() isn't Text aware.
1107                 if (readSoFar > 1 && data[readSoFar - 2] == '\r') {
1108                     --readSoFar;
1109                     data[readSoFar - 1] = '\n';
1110                 }
1111             }
1112             data[readSoFar] = '\0';
1113             return readSoFar;
1114         }
1115     }
1116
1117     if (d->pos != d->devicePos && !sequential && !seek(d->pos))
1118         return qint64(-1);
1119     d->baseReadLineDataCalled = false;
1120     qint64 readBytes = readLineData(data + readSoFar, maxSize - readSoFar);
1121 #if defined QIODEVICE_DEBUG
1122     printf("%p \tread from readLineData: %lld bytes, readSoFar = %lld bytes\n", this,
1123            readBytes, readSoFar);
1124     if (readBytes > 0) {
1125         debugBinaryString(data, int(readSoFar + readBytes));
1126     }
1127 #endif
1128     if (readBytes < 0) {
1129         data[readSoFar] = '\0';
1130         return readSoFar ? readSoFar : -1;
1131     }
1132     readSoFar += readBytes;
1133     if (!d->baseReadLineDataCalled && !sequential) {
1134         d->pos += readBytes;
1135         // If the base implementation was not called, then we must
1136         // assume the device position is invalid and force a seek.
1137         d->devicePos = qint64(-1);
1138     }
1139     data[readSoFar] = '\0';
1140
1141     if (d->openMode & Text) {
1142         if (readSoFar > 1 && data[readSoFar - 1] == '\n' && data[readSoFar - 2] == '\r') {
1143             data[readSoFar - 2] = '\n';
1144             data[readSoFar - 1] = '\0';
1145             --readSoFar;
1146         }
1147     }
1148
1149 #if defined QIODEVICE_DEBUG
1150     printf("%p \treturning %lld, d->pos = %lld, d->buffer.size() = %lld, size() = %lld\n",
1151            this, readSoFar, d->pos, d->buffer.size(), size());
1152     debugBinaryString(data, int(readSoFar));
1153 #endif
1154     return readSoFar;
1155 }
1156
1157 /*!
1158     \overload
1159
1160     Reads a line from the device, but no more than \a maxSize characters,
1161     and returns the result as a byte array.
1162
1163     This function has no way of reporting errors; returning an empty
1164     QByteArray can mean either that no data was currently available
1165     for reading, or that an error occurred.
1166 */
1167 QByteArray QIODevice::readLine(qint64 maxSize)
1168 {
1169     Q_D(QIODevice);
1170     QByteArray result;
1171
1172     CHECK_MAXLEN(readLine, result);
1173
1174 #if defined QIODEVICE_DEBUG
1175     printf("%p QIODevice::readLine(%lld), d->pos = %lld, d->buffer.size() = %lld\n",
1176            this, maxSize, d->pos, d->buffer.size());
1177 #else
1178     Q_UNUSED(d);
1179 #endif
1180
1181     if (quint64(maxSize) >= QByteArray::MaxSize) {
1182         qWarning("QIODevice::read: maxSize argument exceeds QByteArray size limit");
1183         maxSize = QByteArray::MaxSize - 1;
1184     }
1185
1186     result.resize(int(maxSize));
1187     qint64 readBytes = 0;
1188     if (!result.size()) {
1189         // If resize fails or maxSize == 0, read incrementally
1190         if (maxSize == 0)
1191             maxSize = QByteArray::MaxSize - 1;
1192
1193         // The first iteration needs to leave an extra byte for the terminating null
1194         result.resize(1);
1195
1196         qint64 readResult;
1197         do {
1198             result.resize(int(qMin(maxSize, result.size() + QIODEVICE_BUFFERSIZE)));
1199             readResult = readLine(result.data() + readBytes, result.size() - readBytes);
1200             if (readResult > 0 || readBytes == 0)
1201                 readBytes += readResult;
1202         } while (readResult == QIODEVICE_BUFFERSIZE
1203                 && result[int(readBytes - 1)] != '\n');
1204     } else
1205         readBytes = readLine(result.data(), result.size());
1206
1207     if (readBytes <= 0)
1208         result.clear();
1209     else
1210         result.resize(readBytes);
1211
1212     return result;
1213 }
1214
1215 /*!
1216     Reads up to \a maxSize characters into \a data and returns the
1217     number of characters read.
1218
1219     This function is called by readLine(), and provides its base
1220     implementation, using getChar(). Buffered devices can improve the
1221     performance of readLine() by reimplementing this function.
1222
1223     readLine() appends a '\\0' byte to \a data; readLineData() does not
1224     need to do this.
1225
1226     If you reimplement this function, be careful to return the correct
1227     value: it should return the number of bytes read in this line,
1228     including the terminating newline, or 0 if there is no line to be
1229     read at this point. If an error occurs, it should return -1 if and
1230     only if no bytes were read. Reading past EOF is considered an error.
1231 */
1232 qint64 QIODevice::readLineData(char *data, qint64 maxSize)
1233 {
1234     Q_D(QIODevice);
1235     qint64 readSoFar = 0;
1236     char c;
1237     int lastReadReturn = 0;
1238     d->baseReadLineDataCalled = true;
1239
1240     while (readSoFar < maxSize && (lastReadReturn = read(&c, 1)) == 1) {
1241         *data++ = c;
1242         ++readSoFar;
1243         if (c == '\n')
1244             break;
1245     }
1246
1247 #if defined QIODEVICE_DEBUG
1248     printf("%p QIODevice::readLineData(%p, %lld), d->pos = %lld, d->buffer.size() = %lld, "
1249            "returns %lld\n", this, data, maxSize, d->pos, d->buffer.size(), readSoFar);
1250 #endif
1251     if (lastReadReturn != 1 && readSoFar == 0)
1252         return isSequential() ? lastReadReturn : -1;
1253     return readSoFar;
1254 }
1255
1256 /*!
1257     Returns \c true if a complete line of data can be read from the device;
1258     otherwise returns \c false.
1259
1260     Note that unbuffered devices, which have no way of determining what
1261     can be read, always return false.
1262
1263     This function is often called in conjunction with the readyRead()
1264     signal.
1265
1266     Subclasses that reimplement this function must call the base
1267     implementation in order to include the contents of the QIODevice's buffer. Example:
1268
1269     \snippet code/src_corelib_io_qiodevice.cpp 3
1270
1271     \sa readyRead(), readLine()
1272 */
1273 bool QIODevice::canReadLine() const
1274 {
1275     return d_func()->buffer.canReadLine();
1276 }
1277
1278 /*!
1279     Writes at most \a maxSize bytes of data from \a data to the
1280     device. Returns the number of bytes that were actually written, or
1281     -1 if an error occurred.
1282
1283     \sa read(), writeData()
1284 */
1285 qint64 QIODevice::write(const char *data, qint64 maxSize)
1286 {
1287     Q_D(QIODevice);
1288     CHECK_WRITABLE(write, qint64(-1));
1289     CHECK_MAXLEN(write, qint64(-1));
1290
1291     const bool sequential = d->isSequential();
1292     // Make sure the device is positioned correctly.
1293     if (d->pos != d->devicePos && !sequential && !seek(d->pos))
1294         return qint64(-1);
1295
1296 #ifdef Q_OS_WIN
1297     if (d->openMode & Text) {
1298         const char *endOfData = data + maxSize;
1299         const char *startOfBlock = data;
1300
1301         qint64 writtenSoFar = 0;
1302
1303         forever {
1304             const char *endOfBlock = startOfBlock;
1305             while (endOfBlock < endOfData && *endOfBlock != '\n')
1306                 ++endOfBlock;
1307
1308             qint64 blockSize = endOfBlock - startOfBlock;
1309             if (blockSize > 0) {
1310                 qint64 ret = writeData(startOfBlock, blockSize);
1311                 if (ret <= 0) {
1312                     if (writtenSoFar && !sequential)
1313                         d->buffer.skip(writtenSoFar);
1314                     return writtenSoFar ? writtenSoFar : ret;
1315                 }
1316                 if (!sequential) {
1317                     d->pos += ret;
1318                     d->devicePos += ret;
1319                 }
1320                 writtenSoFar += ret;
1321             }
1322
1323             if (endOfBlock == endOfData)
1324                 break;
1325
1326             qint64 ret = writeData("\r\n", 2);
1327             if (ret <= 0) {
1328                 if (writtenSoFar && !sequential)
1329                     d->buffer.skip(writtenSoFar);
1330                 return writtenSoFar ? writtenSoFar : ret;
1331             }
1332             if (!sequential) {
1333                 d->pos += ret;
1334                 d->devicePos += ret;
1335             }
1336             ++writtenSoFar;
1337
1338             startOfBlock = endOfBlock + 1;
1339         }
1340
1341         if (writtenSoFar && !sequential)
1342             d->buffer.skip(writtenSoFar);
1343         return writtenSoFar;
1344     }
1345 #endif
1346
1347     qint64 written = writeData(data, maxSize);
1348     if (written > 0) {
1349         if (!sequential) {
1350             d->pos += written;
1351             d->devicePos += written;
1352         }
1353         if (!d->buffer.isEmpty() && !sequential)
1354             d->buffer.skip(written);
1355     }
1356     return written;
1357 }
1358
1359 /*!
1360     \since 4.5
1361
1362     \overload
1363
1364     Writes data from a zero-terminated string of 8-bit characters to the
1365     device. Returns the number of bytes that were actually written, or
1366     -1 if an error occurred. This is equivalent to
1367     \code
1368     ...
1369     QIODevice::write(data, qstrlen(data));
1370     ...
1371     \endcode
1372
1373     \sa read(), writeData()
1374 */
1375 qint64 QIODevice::write(const char *data)
1376 {
1377     return write(data, qstrlen(data));
1378 }
1379
1380 /*! \fn qint64 QIODevice::write(const QByteArray &byteArray)
1381
1382     \overload
1383
1384     Writes the content of \a byteArray to the device. Returns the number of
1385     bytes that were actually written, or -1 if an error occurred.
1386
1387     \sa read(), writeData()
1388 */
1389
1390 /*!
1391     Puts the character \a c back into the device, and decrements the
1392     current position unless the position is 0. This function is
1393     usually called to "undo" a getChar() operation, such as when
1394     writing a backtracking parser.
1395
1396     If \a c was not previously read from the device, the behavior is
1397     undefined.
1398 */
1399 void QIODevice::ungetChar(char c)
1400 {
1401     Q_D(QIODevice);
1402     CHECK_READABLE(read, Q_VOID);
1403
1404 #if defined QIODEVICE_DEBUG
1405     printf("%p QIODevice::ungetChar(0x%hhx '%c')\n", this, c, isprint(c) ? c : '?');
1406 #endif
1407
1408     d->buffer.ungetChar(c);
1409     if (!d->isSequential())
1410         --d->pos;
1411 }
1412
1413 /*! \fn bool QIODevice::putChar(char c)
1414
1415     Writes the character \a c to the device. Returns \c true on success;
1416     otherwise returns \c false.
1417
1418     \sa write(), getChar(), ungetChar()
1419 */
1420 bool QIODevice::putChar(char c)
1421 {
1422     return d_func()->putCharHelper(c);
1423 }
1424
1425 /*!
1426     \internal
1427 */
1428 bool QIODevicePrivate::putCharHelper(char c)
1429 {
1430     return q_func()->write(&c, 1) == 1;
1431 }
1432
1433 /*!
1434     \internal
1435 */
1436 qint64 QIODevicePrivate::peek(char *data, qint64 maxSize)
1437 {
1438     qint64 readBytes = q_func()->read(data, maxSize);
1439     if (readBytes <= 0)
1440         return readBytes;
1441
1442     buffer.ungetBlock(data, readBytes);
1443     if (!isSequential())
1444         pos -= readBytes;
1445     return readBytes;
1446 }
1447
1448 /*!
1449     \internal
1450 */
1451 QByteArray QIODevicePrivate::peek(qint64 maxSize)
1452 {
1453     QByteArray result = q_func()->read(maxSize);
1454
1455     if (result.isEmpty())
1456         return result;
1457
1458     buffer.ungetBlock(result.constData(), result.size());
1459     if (!isSequential())
1460         pos -= result.size();
1461     return result;
1462 }
1463
1464 /*! \fn bool QIODevice::getChar(char *c)
1465
1466     Reads one character from the device and stores it in \a c. If \a c
1467     is 0, the character is discarded. Returns \c true on success;
1468     otherwise returns \c false.
1469
1470     \sa read(), putChar(), ungetChar()
1471 */
1472 bool QIODevice::getChar(char *c)
1473 {
1474     // readability checked in read()
1475     char ch;
1476     return (1 == read(c ? c : &ch, 1));
1477 }
1478
1479 /*!
1480     \since 4.1
1481
1482     Reads at most \a maxSize bytes from the device into \a data, without side
1483     effects (i.e., if you call read() after peek(), you will get the same
1484     data).  Returns the number of bytes read. If an error occurs, such as
1485     when attempting to peek a device opened in WriteOnly mode, this function
1486     returns -1.
1487
1488     0 is returned when no more data is available for reading.
1489
1490     Example:
1491
1492     \snippet code/src_corelib_io_qiodevice.cpp 4
1493
1494     \sa read()
1495 */
1496 qint64 QIODevice::peek(char *data, qint64 maxSize)
1497 {
1498     return d_func()->peek(data, maxSize);
1499 }
1500
1501 /*!
1502     \since 4.1
1503     \overload
1504
1505     Peeks at most \a maxSize bytes from the device, returning the data peeked
1506     as a QByteArray.
1507
1508     Example:
1509
1510     \snippet code/src_corelib_io_qiodevice.cpp 5
1511
1512     This function has no way of reporting errors; returning an empty
1513     QByteArray can mean either that no data was currently available
1514     for peeking, or that an error occurred.
1515
1516     \sa read()
1517 */
1518 QByteArray QIODevice::peek(qint64 maxSize)
1519 {
1520     return d_func()->peek(maxSize);
1521 }
1522
1523 /*!
1524     Blocks until new data is available for reading and the readyRead()
1525     signal has been emitted, or until \a msecs milliseconds have
1526     passed. If msecs is -1, this function will not time out.
1527
1528     Returns \c true if new data is available for reading; otherwise returns
1529     false (if the operation timed out or if an error occurred).
1530
1531     This function can operate without an event loop. It is
1532     useful when writing non-GUI applications and when performing
1533     I/O operations in a non-GUI thread.
1534
1535     If called from within a slot connected to the readyRead() signal,
1536     readyRead() will not be reemitted.
1537
1538     Reimplement this function to provide a blocking API for a custom
1539     device. The default implementation does nothing, and returns \c false.
1540
1541     \warning Calling this function from the main (GUI) thread
1542     might cause your user interface to freeze.
1543
1544     \sa waitForBytesWritten()
1545 */
1546 bool QIODevice::waitForReadyRead(int msecs)
1547 {
1548     Q_UNUSED(msecs);
1549     return false;
1550 }
1551
1552 /*!
1553     For buffered devices, this function waits until a payload of
1554     buffered written data has been written to the device and the
1555     bytesWritten() signal has been emitted, or until \a msecs
1556     milliseconds have passed. If msecs is -1, this function will
1557     not time out. For unbuffered devices, it returns immediately.
1558
1559     Returns \c true if a payload of data was written to the device;
1560     otherwise returns \c false (i.e. if the operation timed out, or if an
1561     error occurred).
1562
1563     This function can operate without an event loop. It is
1564     useful when writing non-GUI applications and when performing
1565     I/O operations in a non-GUI thread.
1566
1567     If called from within a slot connected to the bytesWritten() signal,
1568     bytesWritten() will not be reemitted.
1569
1570     Reimplement this function to provide a blocking API for a custom
1571     device. The default implementation does nothing, and returns \c false.
1572
1573     \warning Calling this function from the main (GUI) thread
1574     might cause your user interface to freeze.
1575
1576     \sa waitForReadyRead()
1577 */
1578 bool QIODevice::waitForBytesWritten(int msecs)
1579 {
1580     Q_UNUSED(msecs);
1581     return false;
1582 }
1583
1584 /*!
1585     Sets the human readable description of the last device error that
1586     occurred to \a str.
1587
1588     \sa errorString()
1589 */
1590 void QIODevice::setErrorString(const QString &str)
1591 {
1592     d_func()->errorString = str;
1593 }
1594
1595 /*!
1596     Returns a human-readable description of the last device error that
1597     occurred.
1598
1599     \sa setErrorString()
1600 */
1601 QString QIODevice::errorString() const
1602 {
1603     Q_D(const QIODevice);
1604     if (d->errorString.isEmpty()) {
1605 #ifdef QT_NO_QOBJECT
1606         return QLatin1String(QT_TRANSLATE_NOOP(QIODevice, "Unknown error"));
1607 #else
1608         return tr("Unknown error");
1609 #endif
1610     }
1611     return d->errorString;
1612 }
1613
1614 /*!
1615     \fn qint64 QIODevice::readData(char *data, qint64 maxSize)
1616
1617     Reads up to \a maxSize bytes from the device into \a data, and
1618     returns the number of bytes read or -1 if an error occurred.
1619
1620     If there are no bytes to be read and there can never be more bytes
1621     available (examples include socket closed, pipe closed, sub-process
1622     finished), this function returns -1.
1623
1624     This function is called by QIODevice. Reimplement this function
1625     when creating a subclass of QIODevice.
1626
1627     When reimplementing this function it is important that this function
1628     reads all the required data before returning. This is required in order
1629     for QDataStream to be able to operate on the class. QDataStream assumes
1630     all the requested information was read and therefore does not retry reading
1631     if there was a problem.
1632
1633     This function might be called with a maxSize of 0, which can be used to
1634     perform post-reading operations.
1635
1636     \sa read(), readLine(), writeData()
1637 */
1638
1639 /*!
1640     \fn qint64 QIODevice::writeData(const char *data, qint64 maxSize)
1641
1642     Writes up to \a maxSize bytes from \a data to the device. Returns
1643     the number of bytes written, or -1 if an error occurred.
1644
1645     This function is called by QIODevice. Reimplement this function
1646     when creating a subclass of QIODevice.
1647
1648     When reimplementing this function it is important that this function
1649     writes all the data available before returning. This is required in order
1650     for QDataStream to be able to operate on the class. QDataStream assumes
1651     all the information was written and therefore does not retry writing if
1652     there was a problem.
1653
1654     \sa read(), write()
1655 */
1656
1657 /*!
1658   \internal
1659   \fn int qt_subtract_from_timeout(int timeout, int elapsed)
1660
1661   Reduces the \a timeout by \a elapsed, taking into account that -1 is a
1662   special value for timeouts.
1663 */
1664
1665 int qt_subtract_from_timeout(int timeout, int elapsed)
1666 {
1667     if (timeout == -1)
1668         return -1;
1669
1670     timeout = timeout - elapsed;
1671     return timeout < 0 ? 0 : timeout;
1672 }
1673
1674
1675 #if !defined(QT_NO_DEBUG_STREAM)
1676 QDebug operator<<(QDebug debug, QIODevice::OpenMode modes)
1677 {
1678     debug << "OpenMode(";
1679     QStringList modeList;
1680     if (modes == QIODevice::NotOpen) {
1681         modeList << QLatin1String("NotOpen");
1682     } else {
1683         if (modes & QIODevice::ReadOnly)
1684             modeList << QLatin1String("ReadOnly");
1685         if (modes & QIODevice::WriteOnly)
1686             modeList << QLatin1String("WriteOnly");
1687         if (modes & QIODevice::Append)
1688             modeList << QLatin1String("Append");
1689         if (modes & QIODevice::Truncate)
1690             modeList << QLatin1String("Truncate");
1691         if (modes & QIODevice::Text)
1692             modeList << QLatin1String("Text");
1693         if (modes & QIODevice::Unbuffered)
1694             modeList << QLatin1String("Unbuffered");
1695     }
1696     std::sort(modeList.begin(), modeList.end());
1697     debug << modeList.join(QLatin1Char('|'));
1698     debug << ')';
1699     return debug;
1700 }
1701 #endif
1702
1703 QT_END_NAMESPACE