$darkmode
Qore Programming Language - C/C++ Library 1.19.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 - 2023 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 
116  DLLEXPORT int close(ExceptionSink* xsink);
117 
119  DLLEXPORT void setEncoding(const QoreEncoding* cs);
120 
122  DLLEXPORT int setEncoding(const QoreEncoding* cs, ExceptionSink* xsink);
123 
125  DLLEXPORT const QoreEncoding *getEncoding() const;
126 
128  DLLEXPORT int sync();
129 
131  DLLEXPORT int sync(ExceptionSink* xsink);
132 
134 
142 
144 
153  DLLEXPORT QoreStringNode* readLine(bool incl_eol, ExceptionSink* xsink);
154 
156 
164  DLLEXPORT int readLine(QoreString &str);
165 
167 
176  DLLEXPORT int readLine(QoreString &str, bool incl_eol);
177 
179 
189  DLLEXPORT QoreStringNode* readUntil(const char* bytes, bool incl_bytes, ExceptionSink* xsink);
190 
192 
202  DLLEXPORT int readUntil(char byte, QoreString& str, bool incl_bytes = true);
203 
205 
214  DLLEXPORT int readUntil(const char* bytes, QoreString& str, bool incl_bytes = true);
215 
217 
222  DLLEXPORT int write(const QoreString *str, ExceptionSink* xsink);
223 
225 
230  DLLEXPORT int write(const BinaryNode* b, ExceptionSink* xsink);
231 
233 
239  DLLEXPORT int write(const void* data, size_t len, ExceptionSink* xsink);
240 
242 
247  DLLEXPORT int writei1(char i, ExceptionSink* xsink);
248 
250 
256  DLLEXPORT int writei2(short i, ExceptionSink* xsink);
257 
259 
265  DLLEXPORT int writei4(int i, ExceptionSink* xsink);
266 
268 
274  DLLEXPORT int writei8(int64 i, ExceptionSink* xsink);
275 
277 
283  DLLEXPORT int writei2LSB(short i, ExceptionSink* xsink);
284 
286 
292  DLLEXPORT int writei4LSB(int i, ExceptionSink* xsink);
293 
295 
301  DLLEXPORT int writei8LSB(int64 i, ExceptionSink* xsink);
302 
304 
310  DLLEXPORT int readu1(unsigned char *val, ExceptionSink* xsink);
311 
313 
321  DLLEXPORT int readu2(unsigned short *val, ExceptionSink* xsink);
322 
324 
332  DLLEXPORT int readu4(unsigned int *val, ExceptionSink* xsink);
333 
335 
343  DLLEXPORT int readu2LSB(unsigned short *val, ExceptionSink* xsink);
344 
346 
354  DLLEXPORT int readu4LSB(unsigned int *val, ExceptionSink* xsink);
355 
357 
363  DLLEXPORT int readi1(char *val, ExceptionSink* xsink);
364 
366 
374  DLLEXPORT int readi2(short *val, ExceptionSink* xsink);
375 
377 
385  DLLEXPORT int readi4(int *val, ExceptionSink* xsink);
386 
388 
394  DLLEXPORT int readi8(int64 *val, ExceptionSink* xsink);
395 
397 
405  DLLEXPORT int readi2LSB(short *val, ExceptionSink* xsink);
406 
408 
416  DLLEXPORT int readi4LSB(int *val, ExceptionSink* xsink);
417 
419 
425  DLLEXPORT int readi8LSB(int64 *val, ExceptionSink* xsink);
426 
428 
438  DLLEXPORT QoreStringNode* read(qore_offset_t size, ExceptionSink* xsink);
439 
441 
452  DLLEXPORT QoreStringNode* read(qore_offset_t size, int timeout_ms, ExceptionSink* xsink);
453 
455 
462  DLLEXPORT int read(QoreString &str, qore_offset_t size, ExceptionSink* xsink);
463 
465 
472 
474 
480  DLLEXPORT int readBinary(BinaryNode& b, qore_offset_t size, ExceptionSink* xsink);
481 
483 
489  DLLEXPORT BinaryNode* readBinary(qore_offset_t size, int timeout_ms, ExceptionSink* xsink);
490 
492 
499  DLLEXPORT size_t read(void* ptr, size_t limit, int timeout_ms, ExceptionSink* xsink);
500 
502 
504  DLLEXPORT size_t setPos(size_t pos);
505 
507 
510  DLLEXPORT size_t setPos(size_t pos, ExceptionSink* xsink);
511 
513 
516  DLLEXPORT size_t getPos();
517 
519 
521  DLLEXPORT size_t getPos() const;
522 
524 
527  DLLEXPORT QoreStringNode* getchar();
528 
530 
536 
538  DLLEXPORT std::string getFileNameStr() const;
539 
541  DLLEXPORT QoreStringNode* getFileName() const;
542 
543 #ifndef _Q_WINDOWS
545  DLLEXPORT int chown(uid_t owner, gid_t group, ExceptionSink* xsink);
546 
548  DLLEXPORT int lockBlocking(struct flock &fl, ExceptionSink* xsink);
549 
551  DLLEXPORT int lock(const struct flock &fl, ExceptionSink* xsink);
552 
554  DLLEXPORT int getLockInfo(struct flock &fl, ExceptionSink* xsink);
555 #endif
556 
558 
562  DLLEXPORT bool isDataAvailable(int timeout_ms, ExceptionSink* xsink) const;
563 
565 
568  DLLEXPORT QoreListNode* stat(ExceptionSink* xsink) const;
569 
571 
574  DLLEXPORT QoreHashNode* hstat(ExceptionSink* xsink) const;
575 
577 
580  DLLEXPORT QoreHashNode* statvfs(ExceptionSink* xsink) const;
581 
583 
585  DLLEXPORT int redirect(QoreFile& file, ExceptionSink* xsink);
586 
588 
591  DLLEXPORT int getFD() const;
592 
594  DLLEXPORT bool isOpen() const;
595 
597  DLLEXPORT bool isTty() const;
598 
600 
606  DLLEXPORT int detachFd();
607 
609  DLLLOCAL int setTerminalAttributes(int action, QoreTermIOS *ios, ExceptionSink* xsink) const;
610 
612  DLLLOCAL int getTerminalAttributes(QoreTermIOS *ios, ExceptionSink* xsink) const;
613 
614  // NOTE: QoreFile::makeSpecial() can only be called right after the constructor (private API)
615  DLLLOCAL void makeSpecial(int sfd);
616 
618  DLLLOCAL void setEventQueue(ExceptionSink* xsink, Queue* q, QoreValue arg, bool with_data);
619 
621  DLLLOCAL void cleanup(ExceptionSink* xsink);
622 
623 protected:
625  struct qore_qf_private *priv;
626 
628  DLLLOCAL QoreFile(const QoreFile&);
629 
631  DLLLOCAL QoreFile& operator=(const QoreFile&);
632 };
633 
634 DLLEXPORT extern qore_classid_t CID_FILE;
635 DLLEXPORT extern qore_classid_t CID_READONLYFILE;
636 DLLEXPORT extern QoreClass* QC_FILE;
637 DLLEXPORT extern QoreClass* QC_READONLYFILE;
638 
639 class File : public AbstractPollableIoObjectBase, public QoreFile {
640 friend class FileReadPollOperationBase;
641 friend class FileReadPollOperation;
642 public:
643  DLLLOCAL File(const QoreEncoding* cs);
644  DLLLOCAL virtual void deref(ExceptionSink* xsink);
645  DLLLOCAL virtual void deref();
646 
648 
652  DLLLOCAL int getPollableDescriptor() const {
654  }
655 
657 
659  DLLLOCAL QoreObject* startPollRead(ExceptionSink* xsink, QoreObject* self, const char* path, int64 to_read,
660  bool to_string);
661 
662 protected:
663  DLLLOCAL virtual ~File();
664 };
665 
666 class QoreFileHelper : QorePrivateObjectAccessHelper {
667 public:
668  DLLEXPORT QoreFileHelper(QoreObject* obj, ExceptionSink* xsink);
669  DLLEXPORT ~QoreFileHelper();
670  DLLEXPORT QoreFile* operator*() const;
671  DLLEXPORT QoreFile* operator->() const;
672 };
673 
674 #endif // _QORE_QOREFILE_H
DLLEXPORT const QoreEncoding * QCS_DEFAULT
the default encoding for the Qore library
holds arbitrary binary data
Definition: BinaryNode.h:41
container for holding Qore-language exception information and also for registering a "thread_exit" ca...
Definition: ExceptionSink.h:50
defines a Qore-language class
Definition: QoreClass.h:253
defines string encoding functions in Qore
Definition: QoreEncoding.h:83
provides controlled access to file data through Qore data structures
Definition: QoreFile.h:66
DLLEXPORT size_t getPos()
returns the absolute byte position in the file
DLLEXPORT int readu2LSB(unsigned short *val, ExceptionSink *xsink)
reads a 2-byte unsigned integer from the file in LSB (Least Significant Byte first,...
DLLEXPORT int writei8(int64 i, ExceptionSink *xsink)
writes 8-byte (64bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
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)
DLLEXPORT int close()
closes the file
DLLEXPORT int sync()
flushes the write buffer to disk
DLLEXPORT QoreStringNode * readLine(ExceptionSink *xsink)
reads string data from the file up to and including the terminating EOL characters (can be "\n",...
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...
DLLEXPORT void setEncoding(const QoreEncoding *cs)
sets the encoding for the file
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 ...
DLLEXPORT int readu4(unsigned int *val, ExceptionSink *xsink)
reads a 4-byte unsigned integer from the file in MSB (Most Significant Byte first,...
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...
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
DLLLOCAL QoreFile & operator=(const QoreFile &)
this function is not implemented; it is here as a private function in order to prohibit it from being...
DLLEXPORT int lockBlocking(struct flock &fl, ExceptionSink *xsink)
perform a file lock operation
DLLEXPORT QoreHashNode * statvfs(ExceptionSink *xsink) const
returns a QoreHashNode with filesystem status information
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)
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 ...
DLLEXPORT int writei8LSB(int64 i, ExceptionSink *xsink)
writes 8-byte (64bit) binary integer data in LSB (Least Significant Byte first, little endian) format...
DLLEXPORT QoreHashNode * hstat(ExceptionSink *xsink) const
returns a QoreHashNode with file status information
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
DLLEXPORT int getFD() const
get file descriptor
struct qore_qf_private * priv
private implementation
Definition: QoreFile.h:625
DLLEXPORT int lock(const struct flock &fl, ExceptionSink *xsink)
perform a file lock operation, does not block
DLLEXPORT int readi8LSB(int64 *val, ExceptionSink *xsink)
reads an 8-byte signed integer from the file in LSB (Least Significant Byte first,...
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 ...
DLLEXPORT int writei4LSB(int i, ExceptionSink *xsink)
writes 4-byte (32bit) binary integer data in LSB (Least Significant Byte first, little endian)format ...
DLLEXPORT size_t setPos(size_t pos)
sets the absolute file position to "pos"
DLLEXPORT int getLockInfo(struct flock &fl, ExceptionSink *xsink)
get lock info operation, does not block
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...
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
DLLEXPORT int chown(uid_t owner, gid_t group, ExceptionSink *xsink)
changes ownership of the file (if possible)
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
DLLEXPORT int writei4(int i, ExceptionSink *xsink)
writes 4-byte (32bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
DLLEXPORT int writei2LSB(short i, ExceptionSink *xsink)
writes 2-byte (16bit) binary integer data in LSB (Least Significant Byte first, little endian) format...
DLLEXPORT QoreStringNode * getchar()
reads a single byte from the file and returns it as a new string, caller owns the reference count ret...
DLLEXPORT int readu2(unsigned short *val, ExceptionSink *xsink)
reads a 2-byte unsigned integer from the file in MSB (Most Significant Byte first,...
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
DLLLOCAL int getTerminalAttributes(QoreTermIOS *ios, ExceptionSink *xsink) const
gets terminal attributes
DLLEXPORT int writei2(short i, ExceptionSink *xsink)
writes 2-byte (16bit) binary integer data in MSB (Most Significant Byte first, big endian) format to ...
DLLEXPORT QoreListNode * stat(ExceptionSink *xsink) const
returns a QoreListNode with file status information
DLLEXPORT bool isDataAvailable(int timeout_ms, ExceptionSink *xsink) const
returns true if data is available for the file descriptor
DLLLOCAL int setTerminalAttributes(int action, QoreTermIOS *ios, ExceptionSink *xsink) const
sets terminal attributes
DLLEXPORT int readu4LSB(unsigned int *val, ExceptionSink *xsink)
reads a 4-byte unsigned integer from the file in LSB (Least Significant Byte first,...
DLLEXPORT int getPollableDescriptor() const
Returns the underlying file descriptor; -1 if not open.
DLLEXPORT QoreFile(const QoreEncoding *cs=QCS_DEFAULT)
creates the object and sets the default encoding
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 ...
DLLEXPORT const QoreEncoding * getEncoding() const
returns the encoding used for the file
DLLEXPORT QoreStringNode * getFileName() const
returns the filename of the file being read (NULL if no file name is set); caller owns the reference ...
DLLLOCAL void cleanup(ExceptionSink *xsink)
internal API, must be called before deleting the object if an event queue is set
DLLEXPORT int redirect(QoreFile &file, ExceptionSink *xsink)
redirects the current file (this) to the argument
DLLEXPORT ~QoreFile()
closes the file and frees all memory allocated to the object
DLLEXPORT bool isOpen() const
returns true if the file is open, false if not
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 ...
DLLEXPORT bool isTty() const
returns true if the file is a tty
DLLEXPORT int detachFd()
detaches and returns the file descriptor
DLLEXPORT int write(const QoreString *str, ExceptionSink *xsink)
writes string data to the file, character encoding is converted if necessary, and returns the number ...
This is the hash or associative list container type in Qore, dynamically allocated only,...
Definition: QoreHashNode.h:50
This is the list container type in Qore, dynamically allocated only, reference counted.
Definition: QoreListNode.h:52
the implementation of Qore's object data type, reference counted, dynamically-allocated only
Definition: QoreObject.h:60
Qore's string type supported by the QoreEncoding class.
Definition: QoreString.h:93
Qore's string value type, reference counted, dynamically-allocated only.
Definition: QoreStringNode.h:50
unsigned qore_classid_t
used for the unique class ID for QoreClass objects
Definition: common.h:79
intptr_t qore_offset_t
used for offsets that could be negative
Definition: common.h:76
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
The main value class in Qore, designed to be passed by value.
Definition: QoreValue.h:276