1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJ_FILE_IO_H__ 21 #define __PJ_FILE_IO_H__ 22 23 /** 24 * @file file_io.h 25 * @brief Simple file I/O abstraction. 26 */ 27 #include <pj/types.h> 28 29 PJ_BEGIN_DECL 30 31 /** 32 * @defgroup PJ_FILE_IO File I/O 33 * @ingroup PJ_IO 34 * @{ 35 * 36 * This file contains functionalities to perform file I/O. The file 37 * I/O can be implemented with various back-end, either using native 38 * file API or ANSI stream. 39 * 40 * @section pj_file_size_limit_sec Size Limits 41 * 42 * There may be limitation on the size that can be handled by the 43 * #pj_file_setpos() or #pj_file_getpos() functions. The API itself 44 * uses 64-bit integer for the file offset/position (where available); 45 * however some backends (such as ANSI) may only support signed 32-bit 46 * offset resolution. 47 * 48 * Reading and writing operation uses signed 32-bit integer to indicate 49 * the size. 50 * 51 * 52 */ 53 54 /** 55 * These enumerations are used when opening file. Values PJ_O_RDONLY, 56 * PJ_O_WRONLY, and PJ_O_RDWR are mutually exclusive. Value PJ_O_APPEND 57 * can only be used when the file is opened for writing. 58 */ 59 enum pj_file_access 60 { 61 PJ_O_RDONLY = 0x1101, /**< Open file for reading. */ 62 PJ_O_WRONLY = 0x1102, /**< Open file for writing. */ 63 PJ_O_RDWR = 0x1103, /**< Open file for reading and writing. 64 File will be truncated. */ 65 PJ_O_APPEND = 0x1108 /**< Append to existing file. */ 66 }; 67 68 /** 69 * The seek directive when setting the file position with #pj_file_setpos. 70 */ 71 enum pj_file_seek_type 72 { 73 PJ_SEEK_SET = 0x1201, /**< Offset from beginning of the file. */ 74 PJ_SEEK_CUR = 0x1202, /**< Offset from current position. */ 75 PJ_SEEK_END = 0x1203 /**< Size of the file plus offset. */ 76 }; 77 78 /** 79 * Open the file as specified in \c pathname with the specified 80 * mode, and return the handle in \c fd. All files will be opened 81 * as binary. 82 * 83 * @param pool Pool to allocate memory for the new file descriptor. 84 * @param pathname The file name to open. 85 * @param flags Open flags, which is bitmask combination of 86 * #pj_file_access enum. The flag must be either 87 * PJ_O_RDONLY, PJ_O_WRONLY, or PJ_O_RDWR. When file 88 * writing is specified, existing file will be 89 * truncated unless PJ_O_APPEND is specified. 90 * @param fd The returned descriptor. 91 * 92 * @return PJ_SUCCESS or the appropriate error code on error. 93 */ 94 PJ_DECL(pj_status_t) pj_file_open(pj_pool_t *pool, 95 const char *pathname, 96 unsigned flags, 97 pj_oshandle_t *fd); 98 99 /** 100 * Close an opened file descriptor. 101 * 102 * @param fd The file descriptor. 103 * 104 * @return PJ_SUCCESS or the appropriate error code on error. 105 */ 106 PJ_DECL(pj_status_t) pj_file_close(pj_oshandle_t fd); 107 108 /** 109 * Write data with the specified size to an opened file. 110 * 111 * @param fd The file descriptor. 112 * @param data Data to be written to the file. 113 * @param size On input, specifies the size of data to be written. 114 * On return, it contains the number of data actually 115 * written to the file. 116 * 117 * @return PJ_SUCCESS or the appropriate error code on error. 118 */ 119 PJ_DECL(pj_status_t) pj_file_write(pj_oshandle_t fd, 120 const void *data, 121 pj_ssize_t *size); 122 123 /** 124 * Read data from the specified file. When end-of-file condition is set, 125 * this function will return PJ_SUCCESS but the size will contain zero. 126 * 127 * @param fd The file descriptor. 128 * @param data Pointer to buffer to receive the data. 129 * @param size On input, specifies the maximum number of data to 130 * read from the file. On output, it contains the size 131 * of data actually read from the file. It will contain 132 * zero when EOF occurs. 133 * 134 * @return PJ_SUCCESS or the appropriate error code on error. 135 * When EOF occurs, the return is PJ_SUCCESS but size 136 * will report zero. 137 */ 138 PJ_DECL(pj_status_t) pj_file_read(pj_oshandle_t fd, 139 void *data, 140 pj_ssize_t *size); 141 142 /** 143 * Set file position to new offset according to directive \c whence. 144 * 145 * @param fd The file descriptor. 146 * @param offset The new file position to set. 147 * @param whence The directive. 148 * 149 * @return PJ_SUCCESS or the appropriate error code on error. 150 */ 151 PJ_DECL(pj_status_t) pj_file_setpos(pj_oshandle_t fd, 152 pj_off_t offset, 153 enum pj_file_seek_type whence); 154 155 /** 156 * Get current file position. 157 * 158 * @param fd The file descriptor. 159 * @param pos On return contains the file position as measured 160 * from the beginning of the file. 161 * 162 * @return PJ_SUCCESS or the appropriate error code on error. 163 */ 164 PJ_DECL(pj_status_t) pj_file_getpos(pj_oshandle_t fd, 165 pj_off_t *pos); 166 167 /** 168 * Flush file buffers. 169 * 170 * @param fd The file descriptor. 171 * 172 * @return PJ_SUCCESS or the appropriate error code on error. 173 */ 174 PJ_DECL(pj_status_t) pj_file_flush(pj_oshandle_t fd); 175 176 177 /** @} */ 178 179 180 PJ_END_DECL 181 182 #endif /* __PJ_FILE_IO_H__ */ 183 184