/** ** Copyright (c) 2011-2012, Karapetsas Eleftherios ** All rights reserved. ** ** Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: ** 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. ** 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in ** the documentation and/or other materials provided with the distribution. ** 3. Neither the name of the Original Author of Refu nor the names of its contributors may be used to endorse or promote products derived from ** ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, ** INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE ** DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR ** SERVICES;LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, ** WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. **/ #ifndef REFU_IO_H #define REFU_IO_H #include #include #ifdef __cplusplus extern "C" {// opening bracket for calling from C++ #endif // New line feed #define RF_LF 0xA // Carriage Return #define RF_CR 0xD #ifdef REFU_WIN32_VERSION #define i_PLUSB_WIN32 "b" #else #define i_PLUSB_WIN32 "" #endif // This is the type that represents the file offset #ifdef _MSC_VER typedef __int64 foff_rft; #else #include typedef off64_t foff_rft; #endif ///Fseek and Ftelll definitions #ifdef _MSC_VER #define rfFseek(i_FILE_,i_OFFSET_,i_WHENCE_) _fseeki64(i_FILE_,i_OFFSET_,i_WHENCE_) #define rfFtell(i_FILE_) _ftelli64(i_FILE_) #else #define rfFseek(i_FILE_,i_OFFSET_,i_WHENCE_) fseeko64(i_FILE_,i_OFFSET_,i_WHENCE_) #define rfFtell(i_FILE_) ftello64(i_FILE_) #endif /** ** @defgroup RF_IOGRP I/O ** @addtogroup RF_IOGRP ** @{ **/ // @brief Reads a UTF-8 file descriptor until end of line or EOF is found and returns a UTF-8 byte buffer // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // When the compile flag @c RF_NEWLINE_CRLF is defined (the default case at Windows) then this function // shall not be adding any CR character that is found in the file behind a newline character since this is // the Windows line ending scheme. Beware though that the returned read bytes value shall still count the CR character inside. // // @param[in] f The file descriptor to read // @param[out] utf8 Give here a refence to an unitialized char* that will be allocated inside the function // and contain the utf8 byte buffer. Needs to be freed by the caller explicitly later // @param[out] byteLength Give an @c uint32_t here to receive the length of the @c utf8 buffer in bytes // @param[out] bufferSize Give an @c uint32_t here to receive the capacity of the @c utf8 buffer in bytes // @param[out] eof Pass a pointer to a char to receive a true or false value in case the end of file // with reading this line // @return Returns either a positive number for success that represents the number of bytes read from @c f and and error in case something goes wrong. // The possible errors to return are the same as rfFgets_UTF8() i_DECLIMEX_ int32_t rfFReadLine_UTF8(FILE* f,char** utf8,uint32_t* byteLength,uint32_t* bufferSize,char* eof); // @brief Reads a Big Endian UTF-16 file descriptor until end of line or EOF is found and returns a UTF-8 byte buffer // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // When the compile flag @c RF_NEWLINE_CRLF is defined (the default case at Windows) then this function // shall not be adding any CR character that is found in the file behind a newline character since this is // the Windows line ending scheme. Beware though that the returned read bytes value shall still count the CR character inside. // // @param[in] f The file descriptor to read // @param[out] utf8 Give here a refence to an unitialized char* that will be allocated inside the function // and contain the utf8 byte buffer. Needs to be freed by the caller explicitly later // @param[out] byteLength Give an @c uint32_t here to receive the length of the @c utf8 buffer in bytes // @param[out] eof Pass a pointer to a char to receive a true or false value in case the end of file // with reading this line // @return Returns either a positive number for success that represents the number of bytes read from @c f and and error in case something goes wrong. // + Any error that can be returned by @ref rfFgets_UTF16BE() // + @c RE_UTF16_INVALID_SEQUENCE: Failed to decode the UTF-16 byte stream of the file descriptor // + @c RE_UTF8_ENCODING: Failed to encode the UTF-16 of the file descriptor into UTF-8 i_DECLIMEX_ int32_t rfFReadLine_UTF16BE(FILE* f,char** utf8,uint32_t* byteLength,char* eof); // @brief Reads a Little Endian UTF-16 file descriptor until end of line or EOF is found and returns a UTF-8 byte buffer // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // When the compile flag @c RF_NEWLINE_CRLF is defined (the default case at Windows) then this function // shall not be adding any CR character that is found in the file behind a newline character since this is // the Windows line ending scheme. Beware though that the returned read bytes value shall still count the CR character inside. // // @param[in] f The file descriptor to read // @param[out] utf8 Give here a refence to an unitialized char* that will be allocated inside the function // and contain the utf8 byte buffer. Needs to be freed by the caller explicitly later // @param[out] byteLength Give an @c uint32_t here to receive the length of the @c utf8 buffer in bytes // @param[out] eof Pass a pointer to a char to receive a true or false value in case the end of file // with reading this line // @return Returns either a positive number for success that represents the number of bytes read from @c f and and error in case something goes wrong. // + Any error that can be returned by @ref rfFgets_UTF16LE() // + @c RE_UTF16_INVALID_SEQUENCE: Failed to decode the UTF-16 byte stream of the file descriptor // + @c RE_UTF8_ENCODING: Failed to encode the UTF-16 of the file descriptor into UTF-8 i_DECLIMEX_ int32_t rfFReadLine_UTF16LE(FILE* f,char** utf8,uint32_t* byteLength,char* eof); // @brief Reads a Big Endian UTF-32 file descriptor until end of line or EOF is found and returns a UTF-8 byte buffer // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // When the compile flag @c RF_NEWLINE_CRLF is defined (the default case at Windows) then this function // shall not be adding any CR character that is found in the file behind a newline character since this is // the Windows line ending scheme. Beware though that the returned read bytes value shall still count the CR character inside. // // @param[in] f The file descriptor to read // @param[out] utf8 Give here a refence to an unitialized char* that will be allocated inside the function // and contain the utf8 byte buffer. Needs to be freed by the caller explicitly later // @param[out] byteLength Give an @c uint32_t here to receive the length of the @c utf8 buffer in bytes // @param[out] eof Pass a pointer to a char to receive a true or false value in case the end of file // with reading this line // @return Returns either a positive number for success that represents the number of bytes read from @c f and and error in case something goes wrong. // + Any error that can be returned by @ref rfFgets_UTF32BE() // + @c RE_UTF8_ENCODING: Failed to encode the UTF-16 of the file descriptor into UTF-8 i_DECLIMEX_ int32_t rfFReadLine_UTF32BE(FILE* f,char** utf8,uint32_t* byteLength,char* eof); // @brief Reads a Little Endian UTF-32 file descriptor until end of line or EOF is found and returns a UTF-8 byte buffer // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // When the compile flag @c RF_NEWLINE_CRLF is defined (the default case at Windows) then this function // shall not be adding any CR character that is found in the file behind a newline character since this is // the Windows line ending scheme. Beware though that the returned read bytes value shall still count the CR character inside. // // @param[in] f The file descriptor to read // @param[out] utf8 Give here a refence to an unitialized char* that will be allocated inside the function // and contain the utf8 byte buffer. Needs to be freed by the caller explicitly later // @param[out] byteLength Give an @c uint32_t here to receive the length of the @c utf8 buffer in bytes // @param[out] eof Pass a pointer to a char to receive a true or false value in case the end of file // with reading this line // @return Returns either a positive number for success that represents the number of bytes read from @c f and and error in case something goes wrong. // + Any error that can be returned by @ref rfFgets_UTF32LE() // + @c RE_UTF8_ENCODING: Failed to encode the UTF-16 of the file descriptor into UTF-8 i_DECLIMEX_ int32_t rfFReadLine_UTF32LE(FILE* f,char** utf8,uint32_t* byteLength,char* eof); // @brief Gets a number of bytes from a BIG endian UTF-32 file descriptor // // This is a function that's similar to c library fgets but it also returns the number of bytes read. Reads in from the file until @c num bytes // have been read or new line or EOF character has been encountered. // // The function will read until @c num characters are read and if @c num // would take us to the middle of a UTF32 character then the next character shall also be read // and the function will return the number of bytes read. // Since the function null terminates the buffer the given @c buff needs to be of at least // @c num+7 size to cater for the worst case. // // The final bytestream stored inside @c buff is in the endianess of the system. // // If right after the last character read comes the EOF, the function // shall detect so and assign @c true to @c eof. // // In Windows where file endings are in the form of 2 bytes CR-LF (Carriage return - NewLine) this function // shall just ignore the carriage returns and not return it inside the return buffer at @c buff. // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param[in] buff A buffer to be filled with the contents of the file. Should be of size at least @c num+7 // @param[in] num The maximum number of bytes to read from within the file NOT including the null terminating character(which in itelf is 4 bytes). Should be a multiple of 4 // @param[in] f A valid FILE descriptor from which to read the bytes // @param[out] eof Pass a reference to a char to receive a true/false value for whether EOF has been reached. // @return Returns the actual number of bytes read or an error if there was a problem. // The possible errors are: // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgets_UTF32BE(char* buff,uint32_t num,FILE* f,char* eof); // @brief Gets a number of bytes from a Little endian UTF-32 file descriptor // // This is a function that's similar to c library fgets but it also returns the number of bytes read. Reads in from the file until @c num bytes // have been read or new line or EOF character has been encountered. // // The function will read until @c num characters are read and if @c num // would take us to the middle of a UTF32 character then the next character shall also be read // and the function will return the number of bytes read. // Since the function null terminates the buffer the given @c buff needs to be of at least // @c num+7 size to cater for the worst case. // // The final bytestream stored inside @c buff is in the endianess of the system. // // If right after the last character read comes the EOF, the function // shall detect so and assign @c true to @c eof. // // In Windows where file endings are in the form of 2 bytes CR-LF (Carriage return - NewLine) this function // shall just ignore the carriage returns and not return it inside the return buffer at @c buff. // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param[in] buff A buffer to be filled with the contents of the file. Should be of size at least @c num+7 // @param[in] num The maximum number of bytes to read from within the file NOT including the null terminating character(which in itelf is 4 bytes). Should be a multiple of 4 // @param[in] f A valid FILE descriptor from which to read the bytes // @param[out] eof Pass a reference to a char to receive a true/false value for whether EOF has been reached. // @return Returns the actual number of bytes read or an error if there was a problem. // The possible errors are: // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgets_UTF32LE(char* buff,uint32_t num,FILE* f,char* eof); // @brief Gets a number of bytes from a BIG endian UTF-16 file descriptor // // This is a function that's similar to c library fgets but it also returns the number of bytes read. Reads in from the file until @c num bytes // have been read or new line or EOF character has been encountered. // // The function will read until @c num characters are read and if @c num // would take us to the middle of a UTF16 character then the next character shall also be read // and the function will return the number of bytes read. // Since the function null terminates the buffer the given @c buff needs to be of at least // @c num+5 size to cater for the worst case. // // The final bytestream stored inside @c buff is in the endianess of the system. // // If right after the last character read comes the EOF, the function // shall detect so and assign @c true to @c eof. // // In Windows where file endings are in the form of 2 bytes CR-LF (Carriage return - NewLine) this function // shall just ignore the carriage returns and not return it inside the return buffer at @c buff. // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param[in] buff A buffer to be filled with the contents of the file. Should be of size at least @c num+5 // @param[in] num The maximum number of bytes to read from within the file NOT including the null terminating character(which in itelf is 2 bytes). Should be a multiple of 2 // @param[in] f A valid FILE descriptor from which to read the bytes // @param[out] eof Pass a reference to a char to receive a true/false value for whether EOF has been reached. // @return Returns the actual number of bytes read or an error if there was a problem. // The possible errors are: // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgets_UTF16BE(char* buff,uint32_t num,FILE* f,char* eof); // @brief Gets a number of bytes from a Little endian UTF-16 file descriptor // // This is a function that's similar to c library fgets but it also returns the number of bytes read. Reads in from the file until @c num bytes // have been read or new line or EOF character has been encountered. // // The function will read until @c num characters are read and if @c num // would take us to the middle of a UTF16 character then the next character shall also be read // and the function will return the number of bytes read. // Since the function null terminates the buffer the given @c buff needs to be of at least // @c num+5 size to cater for the worst case. // // The final bytestream stored inside @c buff is in the endianess of the system. // // If right after the last character read comes the EOF, the function // shall detect so and assign @c true to @c eof. // // In Windows where file endings are in the form of 2 bytes CR-LF (Carriage return - NewLine) this function // shall just ignore the carriage returns and not return it inside the return buffer at @c buff. // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param[in] buff A buffer to be filled with the contents of the file. Should be of size at least @c num+2 // @param[in] num The maximum number of bytes to read from within the file NOT including the null terminating character(which in itelf is 2 bytes). Should be a multiple of 2 // @param[in] f A valid FILE descriptor from which to read the bytes // @param[out] eof Pass a reference to a char to receive a true/false value for whether EOF has been reached. // @return Returns the actual number of bytes read or an error if there was a problem. // The possible errors are: // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgets_UTF16LE(char* buff,uint32_t num,FILE* f,char* eof); // @brief Gets a number of bytes from a UTF-8 file descriptor // // This is a function that's similar to c library fgets but it also returns the number of bytes read. Reads in from the file until @c num characters // have been read or new line or EOF character has been encountered. // // The function automatically adds a null termination character at the end of // @c buff but this character is not included in the returned actual number of bytes. // // The function will read until @c num characters are read and if @c num // would take us to the middle of a UTF8 character then the next character shall also be read // and the function will return the number of bytes read. // Since the function null terminates the buffer the given @c buff needs to be of at least // @c num+4 size to cater for the worst case. // // If right after the last character read comes the EOF, the function // shall detect so and assign @c true to @c eof. // // In Windows where file endings are in the form of 2 bytes CR-LF (Carriage return - NewLine) this function // shall just ignore the carriage returns and not return it inside the return buffer at @c buff. // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param[in] buff A buffer to be filled with the contents of the file. Should of size at least @c num+4 // @param[in] num The maximum number of bytes to read from within the file NOT including the null terminating character(which in itelf is 1 byte) // @param[in] f A valid FILE descriptor from which to read the bytes // @param[out] eof Pass a reference to a char to receive a true/false value for whether EOF has been reached. // @return Returns the actual number of bytes read or an error if there was a problem. // The possible errors are: // + @c RE_UTF8_INVALID_SEQUENCE_INVALID_BYTE: If an invalid UTF-8 byte has been found // + @c RE_UTF8_INVALID_SEQUENCE_CONBYTE: If during parsing the file we were expecting a continuation // byte and did not find it // + @c RE_UTF8_INVALID_SEQUENCE_END: If the null character is encountered in between bytes that should // have been continuation bytes // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgets_UTF8(char* buff,uint32_t num,FILE* f,char* eof); // @brief Gets a unicode character from a UTF-8 file descriptor // // This function attempts to assume a more modern fgetc() role for UTF-8 encoded files. // Reads bytes from the File descriptor @c f until a full UTF-8 unicode character has been read // // After this function the file pointer will have moved either by @c 1, @c 2, @c 3 or @c 4 // bytes if the return value is positive. You can see how much by checking the return value. // // You shall need to provide an integer at @c c to contain either the decoded Unicode // codepoint or the UTF-8 endoced byte depending on the value of the @c cp argument. // // @param f A valid FILE descriptor from which to read the bytes // @param c Pass an int that will receive either the unicode code point value or // the UTF8 bytes depending on the value of the @c cp flag // @param cp A boolean flag. If @c true then the int passed at @c c will contain the unicode code point // of the read character, so the UTF-8 will be decoded. // If @c false the int passed at @c c will contain the value of the read bytes in UTF-8 without any decoding // @return Returns the number of bytes read (either @c 1, @c 2, @c 3 or @c 4) or an error if the function // fails for some reason. Possible error values are: // + @c RE_FILE_EOF: The end of file has been found while reading. If the end of file is encountered // in the middle of a UTF-8 encoded character where we would be expecting something different // and @c RE_UTF8_INVALID_SEQUENCE_END error is also logged // + @c RE_UTF8_INVALID_SEQUENCE_INVALID_BYTE: If an invalid UTF-8 byte has been found // + @c RE_UTF8_INVALID_SEQUENCE_CONBYTE: If during parsing the file we were expecting a continuation // byte and did not find it // + @c RE_UTF8_INVALID_SEQUENCE_END: If the null character is encountered in between bytes that should // have been continuation bytes // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgetc_UTF8(FILE* f,uint32_t *c,char cp); // @brief Gets a unicode character from a UTF-16 Big Endian file descriptor // // This function attempts to assume a more modern fgetc() role for UTF-16 encoded files. // Reads bytes from the File descriptor @c f until a full UTF-16 unicode character has been read // // After this function the file pointer will have moved either by @c 2 or @c 4 // bytes if the return value is positive. You can see how much by checking the return value. // // You shall need to provide an integer at @c c to contain either the decoded Unicode // codepoint or the Bigendian encoded UTF-16 bytes depending on the value of @c the cp argument. // // @param f A valid FILE descriptor from which to read the bytes // @param c Pass an int that will receive either the unicode code point value or // the UTF16 bytes depending on the value of the @c cp flag // @param cp A boolean flag. If @c true then the int passed at @c c will contain the unicode code point // of the read character, so the UTF-16 will be decoded. // If @c false the int passed at @c c will contain the value of the read bytes in UTF-16 without any decoding // @return Returns the number of bytes read (either @c 2 or @c 4) or an error if the function // fails for some reason. Possible error values are: // + @c RE_UTF16_INVALID_SEQUENCE: Either the read word or its surrogate pair if 4 bytes were read held illegal values // + @c RE_UTF16_NO_SURRPAIR: According to the first read word a surrogate pair was expected but none was found // + @c RE_FILE_EOF: The end of file has been found while reading. If the end of file is encountered // while we expect a UTF-16 surrogate pair an appropriate error is logged // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgetc_UTF16BE(FILE* f,uint32_t *c,char cp); // @brief Gets a unicode character from a UTF-16 Little Endian file descriptor // // This function attempts to assume a more modern fgetc() role for UTF-16 encoded files. // Reads bytes from the File descriptor @c f until a full UTF-16 unicode character has been read // // After this function the file pointer will have moved either by @c 2 or @c 4 // bytes if the return value is positive. You can see how much by checking the return value. // // You shall need to provide an integer at @c c to contain either the decoded Unicode // codepoint or the Bigendian encoded UTF-16 bytes depending on the value of @c the cp argument. // // @param f A valid FILE descriptor from which to read the bytes // @param c Pass an int that will receive either the unicode code point value or // the UTF16 bytes depending on the value of the @c cp flag // @param cp A boolean flag. If @c true then the int passed at @c c will contain the unicode code point // of the read character, so the UTF-16 will be decoded. // If @c false the int passed at @c c will contain the value of the read bytes in UTF-16 without any decoding // @return Returns the number of bytes read (either @c 2 or @c 4) or an error if the function // fails for some reason. Possible error values are: // + @c RE_UTF16_INVALID_SEQUENCE: Either the read word or its surrogate pair if 4 bytes were read held illegal values // + @c RE_UTF16_NO_SURRPAIR: According to the first read word a surrogate pair was expected but none was found // + @c RE_FILE_EOF: The end of file has been found while reading. If the end of file is encountered // while we expect a UTF-16 surrogate pair an appropriate error is logged // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgetc_UTF16LE(FILE* f,uint32_t *c,char cp); // @brief Gets a unicode character from a UTF-32 Little Endian file descriptor // // This function attempts to assume a more modern fgetc() role for UTF-32 encoded files. // Reads bytes from the File descriptor @c f until a full UTF-32 unicode character has been read // // After this function the file pointer will have moved by @c 4 // bytes if the return value is positive. // // You shall need to provide an integer at @c to contain the UTF-32 codepoint. // // @param f A valid FILE descriptor from which to read the bytes // @param c Pass an int that will receive either the unicode code point value or // the UTF16 bytes depending on the value of the @c cp flag // If @c false the int passed at @c c will contain the value of the read bytes in UTF-16 without any decoding // @return Returns either @c RF_SUCCESS for succesfull readin or one of the following errors: // + @c RE_FILE_EOF: The end of file has been found while reading. // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgetc_UTF32LE(FILE* f,uint32_t *c); // @brief Gets a unicode character from a UTF-32 Big Endian file descriptor // // This function attempts to assume a more modern fgetc() role for UTF-32 encoded files. // Reads bytes from the File descriptor @c f until a full UTF-32 unicode character has been read // // After this function the file pointer will have moved by @c 4 // bytes if the return value is positive. // // You shall need to provide an integer at @c to contain the UTF-32 codepoint. // // @param f A valid FILE descriptor from which to read the bytes // @param c Pass an int that will receive either the unicode code point value or // the UTF16 bytes depending on the value of the @c cp flag // If @c false the int passed at @c c will contain the value of the read bytes in UTF-16 without any decoding // @return Returns either @c RF_SUCCESS for succesfull readin or one of the following errors: // + @c RE_FILE_EOF: The end of file has been found while reading. // + @c RE_FILE_READ: If during reading the file there was an unknown read error // + @c RE_FILE_READ_BLOCK: If the read operation failed due to the file descriptor being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the file descriptor's mode was not correctly set for reading // + @c RE_FILE_POS_OVERFLOW: If during reading, the current file position can't be represented by the system // + @c RE_INTERRUPT: If during reading, there was a system interrupt // + @c RE_FILE_IO: If there was a physical I/O error // + @c RE_FILE_NOSPACE: If reading failed due to insufficient storage space i_DECLIMEX_ int32_t rfFgetc_UTF32BE(FILE* f,uint32_t *c); // @brief Moves a unicode character backwards in a big endian UTF-32 file stream // // @param f The file stream // @param c Returns the character we moved back to as a unicode codepoint // @return Returns either @c RF_SUCCESS for success or one of the following errors: // + @c RE_FILE_POS_OVERFLOW: If during trying to read the current file's position it can't be represented by the system // + @c RE_FILE_BAD: If The file descriptor is corrupt/illegal // + @c RE_FILE_NOTFILE: If the file descriptor is not a file but something else. e.g. socket. // + @c RE_FILE_GETFILEPOS: If the file's position could not be retrieved for some unknown reason // + @c RE_FILE_WRITE_BLOCK: While attempting to move the file pointer, it was occupied by another thread, and the no block flag was set // + @c RE_INTERRUPT: Operating on the file failed due to a system interrupt // + @c RE_FILE_IO: There was a physical I/O error // + @c RE_FILE_NOSPACE: There was no space on the device holding the file // + @c RE_FILE_NOTFILE: The device we attempted to manipulate is non-existent // + @c RE_FILE_READ: If during reading the file there was an error // + @c RE_FILE_READ_BLOCK: If during reading the file the read operation failed due to the file being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the underlying file descriptor's mode was not correctly set for reading i_DECLIMEX_ int32_t rfFback_UTF32BE(FILE* f,uint32_t *c); // @brief Moves a unicode character backwards in a little endian UTF-32 file stream // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param f The file stream // @param c Returns the character we moved back to as a unicode codepoint // @return Returns either @c RF_SUCCESS for success or one of the following errors: // + @c RE_FILE_POS_OVERFLOW: If during trying to read the current file's position it can't be represented by the system // + @c RE_FILE_BAD: If The file descriptor is corrupt/illegal // + @c RE_FILE_NOTFILE: If the file descriptor is not a file but something else. e.g. socket. // + @c RE_FILE_GETFILEPOS: If the file's position could not be retrieved for some unknown reason // + @c RE_FILE_WRITE_BLOCK: While attempting to move the file pointer, it was occupied by another thread, and the no block flag was set // + @c RE_INTERRUPT: Operating on the file failed due to a system interrupt // + @c RE_FILE_IO: There was a physical I/O error // + @c RE_FILE_NOSPACE: There was no space on the device holding the file // + @c RE_FILE_NOTFILE: The device we attempted to manipulate is non-existent // + @c RE_FILE_READ: If during reading the file there was an error // + @c RE_FILE_READ_BLOCK: If during reading the file the read operation failed due to the file being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the underlying file descriptor's mode was not correctly set for reading i_DECLIMEX_ int32_t rfFback_UTF32LE(FILE* f,uint32_t *c); // @brief Moves a unicode character backwards in a big endian UTF-16 file stream // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param f The file stream // @param c Returns the character we moved back to as a unicode codepoint // @return Returns either the number of bytes moved backwards (either @c 4 or @c 2) for success or one of the following errors: // + @c RE_UTF16_INVALID_SEQUENCE: Either the read word or its surrogate pair if 4 bytes were read held illegal values // + @c RE_FILE_POS_OVERFLOW: If during trying to read the current file's position it can't be represented by the system // + @c RE_FILE_BAD: If The file descriptor is corrupt/illegal // + @c RE_FILE_NOTFILE: If the file descriptor is not a file but something else. e.g. socket. // + @c RE_FILE_GETFILEPOS: If the file's position could not be retrieved for some unknown reason // + @c RE_FILE_WRITE_BLOCK: While attempting to move the file pointer, it was occupied by another thread, and the no block flag was set // + @c RE_INTERRUPT: Operating on the file failed due to a system interrupt // + @c RE_FILE_IO: There was a physical I/O error // + @c RE_FILE_NOSPACE: There was no space on the device holding the file // + @c RE_FILE_NOTFILE: The device we attempted to manipulate is non-existent // + @c RE_FILE_READ: If during reading the file there was an error // + @c RE_FILE_READ_BLOCK: If during reading the file the read operation failed due to the file being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the underlying file descriptor's mode was not correctly set for reading i_DECLIMEX_ int32_t rfFback_UTF16BE(FILE* f,uint32_t *c); // @brief Moves a unicode character backwards in a little endian UTF-16 file stream // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param f The file stream // @param c Returns the character we moved back to as a unicode codepoint // @return Returns either the number of bytes moved backwards (either @c 4 or @c 2) for success or one of the following errors: // + @c RE_UTF16_INVALID_SEQUENCE: Either the read word or its surrogate pair if 4 bytes were read held illegal values // + @c RE_FILE_POS_OVERFLOW: If during trying to read the current file's position it can't be represented by the system // + @c RE_FILE_BAD: If The file descriptor is corrupt/illegal // + @c RE_FILE_NOTFILE: If the file descriptor is not a file but something else. e.g. socket. // + @c RE_FILE_GETFILEPOS: If the file's position could not be retrieved for some unknown reason // + @c RE_FILE_WRITE_BLOCK: While attempting to move the file pointer, it was occupied by another thread, and the no block flag was set // + @c RE_INTERRUPT: Operating on the file failed due to a system interrupt // + @c RE_FILE_IO: There was a physical I/O error // + @c RE_FILE_NOSPACE: There was no space on the device holding the file // + @c RE_FILE_NOTFILE: The device we attempted to manipulate is non-existent // + @c RE_FILE_READ: If during reading the file there was an error // + @c RE_FILE_READ_BLOCK: If during reading the file the read operation failed due to the file being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the underlying file descriptor's mode was not correctly set for reading i_DECLIMEX_ int32_t rfFback_UTF16LE(FILE* f,uint32_t *c); // @brief Moves a unicode character backwards in a UTF-8 file stream // // The file descriptor at @c f must have been opened in binary and not text mode. That means that if under // Windows make sure to call fopen with "wb", "rb" e.t.c. instead of the simple "w", "r" e.t.c. since the initial // default value under Windows is text mode. Alternatively you can set the initial value using _get_fmode() and // _set_fmode(). For more information take a look at the msdn pages here: // http://msdn.microsoft.com/en-us/library/ktss1a9b.aspx // // @param f The file stream // @param c Returns the character we moved back to as a unicode codepoint // @return Returns either the number of bytes moved backwards for success (either @c 4, @c 3, @c 2 or @c 1) or one of the following errors: // + @c RE_UTF8_INVALID_SEQUENCE: If during moving bacwards in the file unexpected UTF-8 bytes were found // + @c RE_FILE_POS_OVERFLOW: If during trying to read the current file's position it can't be represented by the system // + @c RE_FILE_BAD: If The file descriptor is corrupt/illegal // + @c RE_FILE_NOTFILE: If the file descriptor is not a file but something else. e.g. socket. // + @c RE_FILE_GETFILEPOS: If the file's position could not be retrieved for some unknown reason // + @c RE_FILE_WRITE_BLOCK: While attempting to move the file pointer, it was occupied by another thread, and the no block flag was set // + @c RE_INTERRUPT: Operating on the file failed due to a system interrupt // + @c RE_FILE_IO: There was a physical I/O error // + @c RE_FILE_NOSPACE: There was no space on the device holding the file // + @c RE_FILE_NOTFILE: The device we attempted to manipulate is non-existent // + @c RE_FILE_READ: If during reading the file there was an error // + @c RE_FILE_READ_BLOCK: If during reading the file the read operation failed due to the file being occupied by another thread // + @c RE_FILE_MODE: If during reading the file the underlying file descriptor's mode was not correctly set for reading i_DECLIMEX_ int32_t rfFback_UTF8(FILE* f,uint32_t *c); // @brief Opens another process as a pipe // // This function is a cross-platform popen wrapper. In linux it uses popen and in Windows it uses // _popen. // @lmsFunction // @param command The string with the command to execute. Is basically the name of the program/process you want to spawn // with its full path and its parameters. @inhtype{String,StringX} @tmpSTR // @param mode The mode you want the pipe to work in. There are two possible values: // + @c "r" The calling process can read the spawned command's standard output via the returned stream. // + @c "w" The calling process can write to the spawned command's standard input via the returned stream. // // Anything else will result in an error // @return For success popen will return a FILE descriptor that can be used to either read or write from the pipe. // If there was an error @c 0 is returned and an error is logged. #ifdef RF_IAMHERE_FOR_DOXYGEN i_DECLIMEX_ FILE* rfPopen(void* command,const char* mode); #else i_DECLIMEX_ FILE* i_rfPopen(void* command,const char* mode); #define rfPopen(i_CMD_,i_MODE_) i_rfLMS_WRAP2(FILE*,i_rfPopen,i_CMD_,i_MODE_) #endif // @brief Closes a pipe // // This function is a cross-platform wrapper for pclose. It closes a file descriptor opened with @ref rfPopen() and // returns the exit code of the process that was running // @param stream The file descriptor of the pipe returned by @ref rfPopen() that we want to close // @return Returns the exit code of the process or -1 if there was an error i_DECLIMEX_ int rfPclose(FILE* stream); // @} End of I/O group #ifdef __cplusplus }///closing bracket for calling from C++ #endif #endif//include guards end