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#ifdef __cplusplus 22extern "C" { 23#endif 24 25typedef struct MapFile MapFile; 26 27#ifdef WIN32 28/* Declare constants that are missing in Win32 headers. */ 29#define PROT_READ 0x1 30#define PROT_WRITE 0x2 31#define PROT_EXEC 0x4 32#define PROT_NONE 0x0 33#endif 34 35/* Checks if file handle is a valid one. 36 * Return: 37 * boolean: 1 if handle is valid, or 0 if it's not valid. 38 */ 39static inline int 40mapfile_is_valid(MapFile* handle) 41{ 42 return handle != (void*)(ptrdiff_t)-1; 43} 44 45/* Opens file in selected mode. 46 * Param: 47 * path - Path to the file to open. 48 * oflag - Defines mode in which file is to be opened. This value follows the 49 * symantics of O_XXX flags defined for standard open routine. 50 * share_mode Defines sharing mode for the opened file. This value follows the 51 * symantics of S_IXXX flags defined for standard open routine. 52 * Return: 53 * A valid handle to the opened file on success, or an invalid value on 54 * failure. In case of failure errno contains error code. 55 */ 56extern MapFile* mapfile_open(const char* path, int oflag, int share_mode); 57 58/* Closes a file handle opened with mapfile_open routine. 59 * Param: 60 * handle - A handle to a file previously obtained via successful call to 61 * mapfile_open routine. 62 * Return: 63 * 0 on success, or -1 on failure with errno containing the error code. 64 */ 65extern int mapfile_close(MapFile* handle); 66 67/* Reads from a file opened with mapfile_open routine. 68 * Except for handle parameter, semantics of this call are the same as for 69 * the regualar read routine. 70 * Param: 71 * handle - A handle to a file previously obtained via successful call to 72 * mapfile_open routine. 73 */ 74extern ssize_t mapfile_read(MapFile* handle, void* buf, size_t nbyte); 75 76/* Reads from a specific offset in a file opened with mapfile_open routine. 77 * Param: 78 * handle - A handle to a file previously obtained via successful call to 79 * mapfile_open routine. 80 * offset - Offset in the file where to start reading from. 81 * Rest of the parameters and return value are the same as in file_read. 82 */ 83extern ssize_t mapfile_read_at(MapFile* handle, 84 size_t offset, 85 void* buf, 86 size_t nbyte); 87 88/* Maps a section of a file to memory. 89 * Param: 90 * handle - A handle to a file previously obtained via successful call to 91 * mapfile_open routine. 92 * offset - Offset in the file where mapping should begin. 93 * size - Number of bytes starting with offset that should be mapped. 94 * prot - Determines whether read, write, execute, or some combination of 95 * accesses are permitted to the data being mapped. This parameter has the 96 * same semantics as in regular mmap routene. 97 * mapped_offset - Upon success, contains pointer to the requested offset 98 * within the mapped section of the file. 99 * size - Upon success, contains total number of bytes that were actually 100 * mapped. 101 * Return: 102 * Upon successful completion returns pointer to the beginning of memory 103 * mapping, containing mapping of the requested section of a file. Note that 104 * value returned from this routine doesn't necessarily points to the beginning 105 * of the requested section mapping. Use value returned in mapped_offset 106 * parameter to get actual pointer to the beginning of the requested section 107 * mapping. Value returned from this routine must eventually be passed to 108 * file_unmap_section reoutine to unmap section mapped with this routine. 109 * This routine returns NULL on failure and sets errno to indicate the error. 110 */ 111extern void* mapfile_map(MapFile* handle, 112 size_t offset, 113 size_t size, 114 int prot, 115 void** mapped_offset, 116 size_t* mapped_size); 117 118/* Umaps section of a file previously mapped with mapfile_map routine. 119 * Param: 120 * mapped_at - A pointer to the base address of the mapped section of a file 121 * that is to be unmapped. 122 * len - Byte size of the section that is to be unmapped. 123 * Return: 124 * Upon successful completion returns 0. Otherwise, returns -1 and sets 125 * errno to indicate the error. 126 */ 127extern int mapfile_unmap(void* mapped_at, size_t len); 128 129#ifdef __cplusplus 130} /* end of extern "C" */ 131#endif 132 133#endif // _ANDROID_UTILS_FILEIO_H 134