1 /* Copyright (C) 2007-2010 The Android Open Source Project 2 ** 3 ** This software is licensed under the terms of the GNU General Public 4 ** License version 2, as published by the Free Software Foundation, and 5 ** may be copied, distributed, and modified under those terms. 6 ** 7 ** This program is distributed in the hope that it will be useful, 8 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 9 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 ** GNU General Public License for more details. 11 */ 12 13 /* 14 * Contains declarations of routines that implement platform-independent 15 * file I/O. 16 */ 17 18 #ifndef _ANDROID_UTILS_FILEIO_H 19 #define _ANDROID_UTILS_FILEIO_H 20 21 #include "android/utils/compiler.h" 22 23 #include <stddef.h> 24 #include <unistd.h> 25 26 ANDROID_BEGIN_HEADER 27 28 typedef struct MapFile MapFile; 29 30 #ifdef WIN32 31 /* Declare constants that are missing in Win32 headers. */ 32 #define PROT_READ 0x1 33 #define PROT_WRITE 0x2 34 #define PROT_EXEC 0x4 35 #define PROT_NONE 0x0 36 #endif 37 38 /* Checks if file handle is a valid one. 39 * Return: 40 * boolean: 1 if handle is valid, or 0 if it's not valid. 41 */ 42 static inline int 43 mapfile_is_valid(MapFile* handle) 44 { 45 return handle != (void*)(ptrdiff_t)-1; 46 } 47 48 /* Opens file in selected mode. 49 * Param: 50 * path - Path to the file to open. 51 * oflag - Defines mode in which file is to be opened. This value follows the 52 * symantics of O_XXX flags defined for standard open routine. 53 * share_mode Defines sharing mode for the opened file. This value follows the 54 * symantics of S_IXXX flags defined for standard open routine. 55 * Return: 56 * A valid handle to the opened file on success, or an invalid value on 57 * failure. In case of failure errno contains error code. 58 */ 59 extern MapFile* mapfile_open(const char* path, int oflag, int share_mode); 60 61 /* Closes a file handle opened with mapfile_open routine. 62 * Param: 63 * handle - A handle to a file previously obtained via successful call to 64 * mapfile_open routine. 65 * Return: 66 * 0 on success, or -1 on failure with errno containing the error code. 67 */ 68 extern int mapfile_close(MapFile* handle); 69 70 /* Reads from a file opened with mapfile_open routine. 71 * Except for handle parameter, semantics of this call are the same as for 72 * the regualar read routine. 73 * Param: 74 * handle - A handle to a file previously obtained via successful call to 75 * mapfile_open routine. 76 */ 77 extern ssize_t mapfile_read(MapFile* handle, void* buf, size_t nbyte); 78 79 /* Reads from a specific offset in a file opened with mapfile_open routine. 80 * Param: 81 * handle - A handle to a file previously obtained via successful call to 82 * mapfile_open routine. 83 * offset - Offset in the file where to start reading from. 84 * Rest of the parameters and return value are the same as in file_read. 85 */ 86 extern ssize_t mapfile_read_at(MapFile* handle, 87 size_t offset, 88 void* buf, 89 size_t nbyte); 90 91 /* Maps a section of a file to memory. 92 * Param: 93 * handle - A handle to a file previously obtained via successful call to 94 * mapfile_open routine. 95 * offset - Offset in the file where mapping should begin. 96 * size - Number of bytes starting with offset that should be mapped. 97 * prot - Determines whether read, write, execute, or some combination of 98 * accesses are permitted to the data being mapped. This parameter has the 99 * same semantics as in regular mmap routene. 100 * mapped_offset - Upon success, contains pointer to the requested offset 101 * within the mapped section of the file. 102 * size - Upon success, contains total number of bytes that were actually 103 * mapped. 104 * Return: 105 * Upon successful completion returns pointer to the beginning of memory 106 * mapping, containing mapping of the requested section of a file. Note that 107 * value returned from this routine doesn't necessarily points to the beginning 108 * of the requested section mapping. Use value returned in mapped_offset 109 * parameter to get actual pointer to the beginning of the requested section 110 * mapping. Value returned from this routine must eventually be passed to 111 * file_unmap_section reoutine to unmap section mapped with this routine. 112 * This routine returns NULL on failure and sets errno to indicate the error. 113 */ 114 extern void* mapfile_map(MapFile* handle, 115 size_t offset, 116 size_t size, 117 int prot, 118 void** mapped_offset, 119 size_t* mapped_size); 120 121 /* Umaps section of a file previously mapped with mapfile_map routine. 122 * Param: 123 * mapped_at - A pointer to the base address of the mapped section of a file 124 * that is to be unmapped. 125 * len - Byte size of the section that is to be unmapped. 126 * Return: 127 * Upon successful completion returns 0. Otherwise, returns -1 and sets 128 * errno to indicate the error. 129 */ 130 extern int mapfile_unmap(void* mapped_at, size_t len); 131 132 ANDROID_END_HEADER 133 134 #endif // _ANDROID_UTILS_FILEIO_H 135
