Home | History | Annotate | Download | only in utils 
      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
     22 extern "C" {
     23 #endif
     24 
     25 typedef 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  */
     39 static inline int
     40 mapfile_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  */
     56 extern 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  */
     65 extern 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  */
     74 extern 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  */
     83 extern 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  */
    111 extern 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  */
    127 extern 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