mapfile.h revision d9b6cb97a8a9e93f1bbe5351874b03f7faa81783 
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