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
mapfile_is_valid(MapFile * handle)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