| Qore Programming Language - C/C++ Library 1.12.2

QoreFile.h
1 /* -*- mode: c++; indent-tabs-mode: nil -*- */
2 /*
3 QoreFile.h
4
5 thread-safe File object
6
7 Qore Programming Language
8
9 Copyright (C) 2003 - 2022 Qore Technologies, s.r.o.
10
11 Permission is hereby granted, free of charge, to any person obtaining a
12 copy of this software and associated documentation files (the "Software"),
13 to deal in the Software without restriction, including without limitation
14 the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 and/or sell copies of the Software, and to permit persons to whom the
16 Software is furnished to do so, subject to the following conditions:
17
18 The above copyright notice and this permission notice shall be included in
19 all copies or substantial portions of the Software.
20
21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 DEALINGS IN THE SOFTWARE.
28
29 Note that the Qore library is released under a choice of three open-source
30 licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
31 information.
32 */
33
34 #ifndef _QORE_QOREFILE_H
35
36 #define _QORE_QOREFILE_H
37
38 #include <qore/AbstractPollableIoObjectBase.h>
39
40 #include <fcntl.h>
41 #include <string>
42 #include <sys/file.h>
43 #include <unistd.h>
44
45 /*
46 getchar from stdio.h(included via string on some platforms)
47 is allowed to be defined as a macro and this can cause
48 problems here since the getchar mentioned in this file might
49 get replaced, so we undefine it if it is defined.
50 Undefining getchar is safe since getchar must be defined as
51 a function, so the function is used if the macro is not available.
52 */
53 #ifdef getchar
54 #undef getchar
55 #endif
56
57 class QoreTermIOS;
58 class Queue;
59
61
66 class QoreFile {
67 public:
69 DLLEXPORT QoreFile(const QoreEncoding *cs = QCS_DEFAULT);
70
72 DLLEXPORT ~QoreFile();
73
75
79 DLLEXPORT int getPollableDescriptor() const;
80
82
91 DLLEXPORT int open(const char *fn, int flags = O_RDONLY, int mode = 0777, const QoreEncoding *cs = QCS_DEFAULT);
92
94
104 DLLEXPORT int open2(ExceptionSink *xsink, const char *fn, int flags = O_RDONLY, int mode = 0777, const QoreEncoding *cs = QCS_DEFAULT);
105
107
110 DLLEXPORT int close();
111
113 DLLEXPORT void setEncoding(const QoreEncoding *cs);
114
116 DLLEXPORT const QoreEncoding *getEncoding() const;
117
119 DLLEXPORT int sync();
120
122
129 DLLEXPORT QoreStringNode* readLine(ExceptionSink* xsink);
130
132
141 DLLEXPORT QoreStringNode* readLine(bool incl_eol, ExceptionSink* xsink);
142
144
152 DLLEXPORT int readLine(QoreString &str);
153
155
164 DLLEXPORT int readLine(QoreString &str, bool incl_eol);
165
167
177 DLLEXPORT QoreStringNode* readUntil(const char* bytes, bool incl_bytes, ExceptionSink* xsink);
178
180
190 DLLEXPORT int readUntil(char byte, QoreString& str, bool incl_bytes = true);
191
193
202 DLLEXPORT int readUntil(const char* bytes, QoreString& str, bool incl_bytes = true);
203
205
210 DLLEXPORT int write(const QoreString *str, ExceptionSink *xsink);
211
213
218 DLLEXPORT int write(const BinaryNode *b, ExceptionSink *xsink);
219
221
227 DLLEXPORT int write(const void *data, size_t len, ExceptionSink *xsink);
228
230
235 DLLEXPORT int writei1(char i, ExceptionSink *xsink);
236
238
244 DLLEXPORT int writei2(short i, ExceptionSink *xsink);
245
247
253 DLLEXPORT int writei4(int i, ExceptionSink *xsink);
254
256
262 DLLEXPORT int writei8(int64 i, ExceptionSink *xsink);
263
265
271 DLLEXPORT int writei2LSB(short i, ExceptionSink *xsink);
272
274
280 DLLEXPORT int writei4LSB(int i, ExceptionSink *xsink);
281
283
289 DLLEXPORT int writei8LSB(int64 i, ExceptionSink *xsink);
290
292
298 DLLEXPORT int readu1(unsigned char *val, ExceptionSink *xsink);
299
301
309 DLLEXPORT int readu2(unsigned short *val, ExceptionSink *xsink);
310
312
320 DLLEXPORT int readu4(unsigned int *val, ExceptionSink *xsink);
321
323
331 DLLEXPORT int readu2LSB(unsigned short *val, ExceptionSink *xsink);
332
334
342 DLLEXPORT int readu4LSB(unsigned int *val, ExceptionSink *xsink);
343
345
351 DLLEXPORT int readi1(char *val, ExceptionSink *xsink);
352
354
362 DLLEXPORT int readi2(short *val, ExceptionSink *xsink);
363
365
373 DLLEXPORT int readi4(int *val, ExceptionSink *xsink);
374
376
382 DLLEXPORT int readi8(int64 *val, ExceptionSink *xsink);
383
385
393 DLLEXPORT int readi2LSB(short *val, ExceptionSink *xsink);
394
396
404 DLLEXPORT int readi4LSB(int *val, ExceptionSink *xsink);
405
407
413 DLLEXPORT int readi8LSB(int64 *val, ExceptionSink *xsink);
414
416
426 DLLEXPORT QoreStringNode *read(qore_offset_t size, ExceptionSink *xsink);
427
429
440 DLLEXPORT QoreStringNode* read(qore_offset_t size, int timeout_ms, ExceptionSink *xsink);
441
443
450 DLLEXPORT int read(QoreString &str, qore_offset_t size, ExceptionSink *xsink);
451
453
459 DLLEXPORT BinaryNode *readBinary(qore_offset_t size, ExceptionSink *xsink);
460
462
468 DLLEXPORT int readBinary(BinaryNode &b, qore_offset_t size, ExceptionSink *xsink);
469
471
477 DLLEXPORT BinaryNode *readBinary(qore_offset_t size, int timeout_ms, ExceptionSink *xsink);
478
480
487 DLLEXPORT size_t read(void *ptr, size_t limit, int timeout_ms, ExceptionSink *xsink);
488
490
492 DLLEXPORT size_t setPos(size_t pos);
493
495
498 DLLEXPORT size_t getPos();
499
501
503 DLLEXPORT size_t getPos() const;
504
506
509 DLLEXPORT QoreStringNode *getchar();
510
512
517 DLLEXPORT QoreStringNode *getchar(ExceptionSink *xsink);
518
520 DLLEXPORT std::string getFileNameStr() const;
521
523 DLLEXPORT QoreStringNode* getFileName() const;
524
525 #ifndef _Q_WINDOWS
527 DLLEXPORT int chown(uid_t owner, gid_t group, ExceptionSink *xsink);
528
530 DLLEXPORT int lockBlocking(struct flock &fl, ExceptionSink *xsink);
531
533 DLLEXPORT int lock(const struct flock &fl, ExceptionSink *xsink);
534
536 DLLEXPORT int getLockInfo(struct flock &fl, ExceptionSink *xsink);
537 #endif
538
540
544 DLLEXPORT bool isDataAvailable(int timeout_ms, ExceptionSink *xsink) const;
545
547
550 DLLEXPORT QoreListNode *stat(ExceptionSink *xsink) const;
551
553
556 DLLEXPORT QoreHashNode *hstat(ExceptionSink *xsink) const;
557
559
562 DLLEXPORT QoreHashNode *statvfs(ExceptionSink *xsink) const;
563
565
567 DLLEXPORT int redirect(QoreFile& file, ExceptionSink* xsink);
568
570
573 DLLEXPORT int getFD() const;
574
576 DLLEXPORT bool isOpen() const;
577
579 DLLEXPORT bool isTty() const;
580
582
588 DLLEXPORT int detachFd();
589
591 DLLLOCAL int setTerminalAttributes(int action, QoreTermIOS *ios, ExceptionSink *xsink) const;
592
594 DLLLOCAL int getTerminalAttributes(QoreTermIOS *ios, ExceptionSink *xsink) const;
595
596 // NOTE: QoreFile::makeSpecial() can only be called right after the constructor (private API)
597 DLLLOCAL void makeSpecial(int sfd);
598
600 DLLLOCAL void setEventQueue(ExceptionSink* xsink, Queue* q, QoreValue arg, bool with_data);
601
603 DLLLOCAL void cleanup(ExceptionSink *xsink);
604
605 protected:
607 struct qore_qf_private *priv;
608
610 DLLLOCAL QoreFile(const QoreFile&);
611
613 DLLLOCAL QoreFile& operator=(const QoreFile&);
614 };
615
616 DLLEXPORT extern qore_classid_t CID_FILE;
617 DLLEXPORT extern QoreClass* QC_FILE;
618 DLLEXPORT extern QoreClass* QC_READONLYFILE;
619
620 class File : public AbstractPollableIoObjectBase, public QoreFile {
621 protected:
622 DLLLOCAL virtual ~File();
623
624 public:
625 DLLLOCAL File(const QoreEncoding* cs);
626 DLLLOCAL virtual void deref(ExceptionSink* xsink);
627 DLLLOCAL virtual void deref();
628
630
634 DLLLOCAL int getPollableDescriptor() const {
635 return QoreFile::getPollableDescriptor();
636 }
637 };
638
639 class QoreFileHelper : QorePrivateObjectAccessHelper {
640 public:
641 DLLEXPORT QoreFileHelper(QoreObject* obj, ExceptionSink* xsink);
642 DLLEXPORT ~QoreFileHelper();
643 DLLEXPORT QoreFile* operator*() const;
644 DLLEXPORT QoreFile* operator->() const;
645 };
646
647 #endif // _QORE_QOREFILE_H
QCS_DEFAULT
DLLEXPORT const QoreEncoding * QCS_DEFAULT
the default encoding for the Qore library
BinaryNode
holds arbitrary binary data
Definition: BinaryNode.h:41
ExceptionSink
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:48
QoreClass
defines a Qore-language class
Definition: QoreClass.h:249
QoreEncoding
defines string encoding functions in Qore
Definition: QoreEncoding.h:83
QoreFile
provides controlled access to file data through Qore data structures
Definition: QoreFile.h:66
QoreFile::getPos
DLLEXPORT size_t getPos()
returns the absolute byte position in the file
QoreFile::readu2LSB
DLLEXPORT int readu2LSB(unsigned short *val, ExceptionSink *xsink)
reads a 2-byte unsigned integer from the file in LSB (Least Significant Byte first,...
QoreFile::writei8
DLLEXPORT int writei8(int64 i, ExceptionSink *xsink)
writes 8-byte (64bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
QoreFile::writei1
DLLEXPORT int writei1(char i, ExceptionSink *xsink)
writes 1-byte binary integer data to the file and returns the number of bytes written (normally 1)
QoreFile::close
DLLEXPORT int close()
closes the file
QoreFile::sync
DLLEXPORT int sync()
flushes the write buffer to disk
QoreFile::readLine
DLLEXPORT QoreStringNode * readLine(ExceptionSink *xsink)
reads string data from the file up to and including the terminating EOL characters (can be "\n",...
QoreFile::read
DLLEXPORT QoreStringNode * read(qore_offset_t size, ExceptionSink *xsink)
reads string data from the file and returns the string read (caller owns the reference count returned...
QoreFile::setEncoding
DLLEXPORT void setEncoding(const QoreEncoding *cs)
sets the encoding for the file
QoreFile::readi4LSB
DLLEXPORT int readi4LSB(int *val, ExceptionSink *xsink)
reads a 4-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format ...
QoreFile::readu4
DLLEXPORT int readu4(unsigned int *val, ExceptionSink *xsink)
reads a 4-byte unsigned integer from the file in MSB (Most Significant Byte first,...
QoreFile::readi2
DLLEXPORT int readi2(short *val, ExceptionSink *xsink)
reads a 2-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format a...
QoreFile::readi1
DLLEXPORT int readi1(char *val, ExceptionSink *xsink)
reads a 1-byte signed integer from the file and returns the value read as an output parameter
QoreFile::operator=
DLLLOCAL QoreFile & operator=(const QoreFile &)
this function is not implemented; it is here as a private function in order to prohibit it from being...
QoreFile::lockBlocking
DLLEXPORT int lockBlocking(struct flock &fl, ExceptionSink *xsink)
perform a file lock operation
QoreFile::statvfs
DLLEXPORT QoreHashNode * statvfs(ExceptionSink *xsink) const
returns a QoreHashNode with filesystem status information
QoreFile::readBinary
DLLEXPORT BinaryNode * readBinary(qore_offset_t size, ExceptionSink *xsink)
reads binary data from the file and returns the data read (caller owns the reference count returned)
QoreFile::readi2LSB
DLLEXPORT int readi2LSB(short *val, ExceptionSink *xsink)
reads a 2-byte signed integer from the file in LSB (Least Significant Byte first, big endian) format ...
QoreFile::writei8LSB
DLLEXPORT int writei8LSB(int64 i, ExceptionSink *xsink)
writes 8-byte (64bit) binary integer data in LSB (Least Significant Byte first, little endian) format...
QoreFile::hstat
DLLEXPORT QoreHashNode * hstat(ExceptionSink *xsink) const
returns a QoreHashNode with file status information
QoreFile::setEventQueue
DLLLOCAL void setEventQueue(ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data)
sets the event queue (not part of the library's pubilc API), must be already referenced before call
QoreFile::getFD
DLLEXPORT int getFD() const
get file descriptor
QoreFile::priv
struct qore_qf_private * priv
private implementation
Definition: QoreFile.h:607
QoreFile::lock
DLLEXPORT int lock(const struct flock &fl, ExceptionSink *xsink)
perform a file lock operation, does not block
QoreFile::readi8LSB
DLLEXPORT int readi8LSB(int64 *val, ExceptionSink *xsink)
reads an 8-byte signed integer from the file in LSB (Least Significant Byte first,...
QoreFile::readi8
DLLEXPORT int readi8(int64 *val, ExceptionSink *xsink)
reads an 8-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format ...
QoreFile::writei4LSB
DLLEXPORT int writei4LSB(int i, ExceptionSink *xsink)
writes 4-byte (32bit) binary integer data in LSB (Least Significant Byte first, little endian)format ...
QoreFile::setPos
DLLEXPORT size_t setPos(size_t pos)
sets the absolute file position to "pos"
QoreFile::getLockInfo
DLLEXPORT int getLockInfo(struct flock &fl, ExceptionSink *xsink)
get lock info operation, does not block
QoreFile::readi4
DLLEXPORT int readi4(int *val, ExceptionSink *xsink)
reads a 4-byte signed integer from the file in MSB (Most Significant Byte first, big endian) format a...
QoreFile::open2
DLLEXPORT int open2(ExceptionSink *xsink, const char *fn, int flags=O_RDONLY, int mode=0777, const QoreEncoding *cs=QCS_DEFAULT)
opens the file and raises a Qore-language exception if an error occurs
QoreFile::chown
DLLEXPORT int chown(uid_t owner, gid_t group, ExceptionSink *xsink)
changes ownership of the file (if possible)
QoreFile::readu1
DLLEXPORT int readu1(unsigned char *val, ExceptionSink *xsink)
reads a 1-byte unsigned integer from the file and returns the value read as an output parameter
QoreFile::writei4
DLLEXPORT int writei4(int i, ExceptionSink *xsink)
writes 4-byte (32bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
QoreFile::writei2LSB
DLLEXPORT int writei2LSB(short i, ExceptionSink *xsink)
writes 2-byte (16bit) binary integer data in LSB (Least Significant Byte first, little endian) format...
QoreFile::getchar
DLLEXPORT QoreStringNode * getchar()
reads a single byte from the file and returns it as a new string, caller owns the reference count ret...
QoreFile::readu2
DLLEXPORT int readu2(unsigned short *val, ExceptionSink *xsink)
reads a 2-byte unsigned integer from the file in MSB (Most Significant Byte first,...
QoreFile::open
DLLEXPORT int open(const char *fn, int flags=O_RDONLY, int mode=0777, const QoreEncoding *cs=QCS_DEFAULT)
opens the file and returns 0 for success, non-zero for error
QoreFile::getTerminalAttributes
DLLLOCAL int getTerminalAttributes(QoreTermIOS *ios, ExceptionSink *xsink) const
gets terminal attributes
QoreFile::writei2
DLLEXPORT int writei2(short i, ExceptionSink *xsink)
writes 2-byte (16bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
QoreFile::stat
DLLEXPORT QoreListNode * stat(ExceptionSink *xsink) const
returns a QoreListNode with file status information
QoreFile::isDataAvailable
DLLEXPORT bool isDataAvailable(int timeout_ms, ExceptionSink *xsink) const
returns true if data is available for the file descriptor
QoreFile::setTerminalAttributes
DLLLOCAL int setTerminalAttributes(int action, QoreTermIOS *ios, ExceptionSink *xsink) const
sets terminal attributes
QoreFile::readu4LSB
DLLEXPORT int readu4LSB(unsigned int *val, ExceptionSink *xsink)
reads a 4-byte unsigned integer from the file in LSB (Least Significant Byte first,...
QoreFile::getPollableDescriptor
DLLEXPORT int getPollableDescriptor() const
Returns the underlying file descriptor; -1 if not open.
QoreFile::QoreFile
DLLEXPORT QoreFile(const QoreEncoding *cs=QCS_DEFAULT)
creates the object and sets the default encoding
QoreFile::getFileNameStr
DLLEXPORT std::string getFileNameStr() const
returns the filename of the file being read as a std::string (the string is empty if no file name is ...
QoreFile::getEncoding
DLLEXPORT const QoreEncoding * getEncoding() const
returns the encoding used for the file
QoreFile::getFileName
DLLEXPORT QoreStringNode * getFileName() const
returns the filename of the file being read (NULL if no file name is set); caller owns the reference ...
QoreFile::cleanup
DLLLOCAL void cleanup(ExceptionSink *xsink)
internal API, must be called before deleting the object if an event queue is set
QoreFile::redirect
DLLEXPORT int redirect(QoreFile &file, ExceptionSink *xsink)
redirects the current file (this) to the argument
QoreFile::~QoreFile
DLLEXPORT ~QoreFile()
closes the file and frees all memory allocated to the object
QoreFile::isOpen
DLLEXPORT bool isOpen() const
returns true if the file is open, false if not
QoreFile::readUntil
DLLEXPORT QoreStringNode * readUntil(const char *bytes, bool incl_bytes, ExceptionSink *xsink)
reads string data from the file up to and optionally including the terminating EOL characters passed ...
QoreFile::isTty
DLLEXPORT bool isTty() const
returns true if the file is a tty
QoreFile::detachFd
DLLEXPORT int detachFd()
detaches and returns the file descriptor
QoreFile::write
DLLEXPORT int write(const QoreString *str, ExceptionSink *xsink)
writes string data to the file, character encoding is converted if necessary, and returns the number ...
QoreHashNode
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
QoreListNode
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
QoreObject
the implementation of Qore's object data type, reference counted, dynamically-allocated only
Definition: QoreObject.h:60
QoreString
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
QoreStringNode
Qore's string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
qore_classid_t
unsigned qore_classid_t
used for the unique class ID for QoreClass objects
Definition: common.h:79
qore_offset_t
intptr_t qore_offset_t
used for offsets that could be negative
Definition: common.h:76
int64
long long int64
64bit integer type, cannot use int64_t here since it breaks the API on some 64-bit systems due to equ...
Definition: common.h:260
QoreValue
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:275