1/* Copyright (C) 2007-2009 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#ifndef _ANDROID_UTILS_PATH_H
13#define _ANDROID_UTILS_PATH_H
14
15#include <android/utils/compiler.h>
16#include <android/utils/system.h>
17#include <stdint.h>  /* for uint64_t */
18
19ANDROID_BEGIN_HEADER
20
21/** MISC FILE AND DIRECTORY HANDLING
22 **/
23
24/* O_BINARY is required in the MS C library to avoid opening file
25 * in text mode (the default, ahhhhh)
26 */
27#if !defined(_WIN32) && !defined(O_BINARY)
28#  define  O_BINARY  0
29#endif
30
31/* define  PATH_SEP as a string containing the directory separateor */
32#ifdef _WIN32
33#  define  PATH_SEP   "\\"
34#  define  PATH_SEP_C '\\'
35#else
36#  define  PATH_SEP   "/"
37#  define  PATH_SEP_C '/'
38#endif
39
40/* get MAX_PATH, note that PATH_MAX is set to 260 on Windows for
41 * stupid backwards-compatibility reason, though any 32-bit version
42 * of the OS handles much much longer paths
43 */
44#ifdef _WIN32
45#  undef   MAX_PATH
46#  define  MAX_PATH    1024
47#  undef   PATH_MAX
48#  define  PATH_MAX    MAX_PATH
49#else
50#  include <limits.h>
51#  define  MAX_PATH    PATH_MAX
52#endif
53
54/* checks that a given file exists */
55extern ABool  path_exists( const char*  path );
56
57/* checks that a path points to a regular file */
58extern ABool  path_is_regular( const char*  path );
59
60/* checks that a path points to a directory */
61extern ABool  path_is_dir( const char*  path );
62
63/* checks that a path is absolute or not */
64extern ABool  path_is_absolute( const char*  path );
65
66/* checks that one can read/write a given (regular) file */
67extern ABool  path_can_read( const char*  path );
68extern ABool  path_can_write( const char*  path );
69
70/* checks that one can execute a given file */
71extern ABool  path_can_exec( const char* path );
72
73/* try to make a directory */
74extern APosixStatus   path_mkdir( const char*  path, int  mode );
75
76/* ensure that a given directory exists, create it if not,
77   0 on success, -1 on error */
78extern APosixStatus   path_mkdir_if_needed( const char*  path, int  mode );
79
80/* return the size of a given file in '*psize'. returns 0 on
81 * success, -1 on failure (error code in errno) */
82extern APosixStatus   path_get_size( const char*  path, uint64_t  *psize );
83
84/*  path_parent() can be used to return the n-level parent of a given directory
85 *  this understands . and .. when encountered in the input path.
86 *
87 *  the returned string must be freed by the caller.
88 */
89extern char*  path_parent( const char*  path, int  levels );
90
91/* split a path into a (dirname,basename) pair. the result strings must be freed
92 * by the caller. Return 0 on success, or -1 on error. Error conditions include
93 * the following:
94 *   - 'path' is empty
95 *   - 'path' is "/" or degenerate cases like "////"
96 *   - basename is "." or ".."
97 *
98 * if there is no directory separator in path, *dirname will be set to "."
99 * if the path is of type "/foo", then *dirname will be set to "/"
100 *
101 * pdirname can be NULL if you don't want the directory name
102 * pbasename can be NULL if you don't want the base name
103 */
104extern int    path_split( const char*  path, char* *pdirname, char* *pbasename );
105
106/* a convenience function to retrieve the directory name as returned by
107 * path_split(). Returns NULL if path_split() returns an error.
108 * the result string must be freed by the caller
109 */
110extern char*  path_dirname( const char*  path );
111
112/* a convenience function to retrieve the base name as returned by
113 * path_split(). Returns NULL if path_split() returns an error.
114 * the result must be freed by the caller.
115 */
116extern char*  path_basename( const char*  path );
117
118/* look for a given executable in the system path and return its full path.
119 * Returns NULL if not found. Note that on Windows this doesn't not append
120 * an .exe prefix, or other magical thing like Cygwin usually does.
121 */
122extern char*  path_search_exec( const char* filename );
123
124/* Return the absolute version of a path. If 'path' is already absolute,
125 * this will be a simple copy. Otherwise, this function will prepend the
126 * current working directory to the result.
127 */
128extern char*  path_get_absolute( const char* path );
129
130/** OTHER FILE UTILITIES
131 **
132 **  path_empty_file() creates an empty file at a given path location.
133 **  if the file already exists, it is truncated without warning
134 **
135 **  path_copy_file() copies one file into another.
136 **
137 **  unlink_file() is equivalent to unlink() on Unix, on Windows,
138 **  it will handle the case where _unlink() fails because the file is
139 **  read-only by trying to change its access rights then calling _unlink()
140 **  again.
141 **
142 **  these functions return 0 on success, and -1 on error
143 **
144 **  load_text_file() reads a file into a heap-allocated memory block,
145 **  and appends a 0 to it. the caller must free it
146 **/
147
148/* creates an empty file at a given location. If the file already
149 * exists, it is truncated without warning. returns 0 on success,
150 * or -1 on failure.
151 */
152extern APosixStatus   path_empty_file( const char*  path );
153
154/* copies on file into another one. 0 on success, -1 on failure
155 * (error code in errno). Does not work on directories */
156extern APosixStatus   path_copy_file( const char*  dest, const char*  source );
157
158/* unlink/delete a given file. Note that on Win32, this will
159 * fail if the program has an opened handle to the file
160 */
161extern APosixStatus   path_delete_file( const char*  path );
162
163/* try to load a given file into a heap-allocated block.
164 * if 'pSize' is not NULL, this will set the file's size in '*pSize'
165 * note that this actually zero-terminates the file for convenience.
166 * In case of failure, NULL is returned and the error code is in errno
167 */
168extern void*          path_load_file( const char*  path, size_t  *pSize );
169
170/* */
171ANDROID_END_HEADER
172
173#endif /* _ANDROID_UTILS_PATH_H */
174