VLC 4.0.0-dev
Loading...
Searching...
No Matches
vlc_fs.h
Go to the documentation of this file.
1/*****************************************************************************
2 * vlc_fs.h: File system helpers
3 *****************************************************************************
4 * Copyright © 2006-2010 Rémi Denis-Courmont
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
20
21#ifndef VLC_FS_H
22#define VLC_FS_H 1
23
24#include <sys/types.h>
25
26struct stat;
27struct iovec;
28
29#ifdef _WIN32
30# include <io.h>
31# include <sys/stat.h>
32# ifndef stat
33# define stat _stati64
34# endif
35# ifndef fstat
36# define fstat _fstati64
37# endif
38# undef lseek
39# define lseek _lseeki64
40#else // !_WIN32
41#include <dirent.h>
42#endif
43
44#ifdef __ANDROID__
45# define lseek lseek64
46#endif
47
48
49/**
50 * \defgroup os Operating system
51 * \ingroup vlc
52 * \defgroup file File system
53 * \ingroup os
54 * @{
55 *
56 * \file
57 * The functions in this file help with using low-level Unix-style file
58 * descriptors, BSD sockets and directories. In general, they retain the
59 * prototype and most semantics from their respective standard equivalents.
60 * However, there are a few differences:
61 * - On Windows, file path arguments are expected in UTF-8 format.
62 * They are converted to UTF-16 internally, thus enabling access to paths
63 * outside of the local Windows ANSI code page.
64 * - On POSIX systems, file descriptors are created with the close-on-exec
65 * flag set (atomically where possible), so that they do not leak to
66 * child process after fork-and-exec.
67 * - vlc_scandir(), inspired by GNU scandir(), passes file names rather than
68 * dirent structure pointers to its callbacks.
69 * - vlc_accept() takes an extra boolean for nonblocking mode (compare with
70 * the flags parameter in POSIX.next accept4()).
71 * - Writing functions do not emit a SIGPIPE signal in case of broken pipe.
72 *
73 * \defgroup fd File descriptors
74 * @{
75 */
76
77/**
78 * Opens a system file handle.
79 *
80 * @param filename file path to open (with UTF-8 encoding)
81 * @param flags open() flags, see the C library open() documentation
82 * @return a file handle on success, -1 on error (see errno).
83 * @note Contrary to standard open(), this function returns a file handle
84 * with the close-on-exec flag preset.
85 */
86VLC_API int vlc_open(const char *filename, int flags, ...) VLC_USED;
87
88/**
89 * Opens a system file handle relative to an existing directory handle.
90 *
91 * @param dir directory file descriptor
92 * @param filename file path to open (with UTF-8 encoding)
93 * @param flags open() flags, see the C library open() documentation
94 * @return a file handle on success, -1 on error (see errno).
95 * @note Contrary to standard open(), this function returns a file handle
96 * with the close-on-exec flag preset.
97 */
98VLC_API int vlc_openat(int dir, const char *filename, int flags, ...) VLC_USED;
99
100VLC_API int vlc_mkstemp( char * );
101
102/**
103 * Duplicates a file descriptor.
104 *
105 * @param oldfd file descriptor to duplicate
106 *
107 * @note Contrary to standard dup(), the new file descriptor has the
108 * close-on-exec descriptor flag preset.
109 * @return a new file descriptor, -1 (see @c errno)
110 */
111VLC_API int vlc_dup(int oldfd) VLC_USED;
112
113/**
114 * Replaces a file descriptor.
115 *
116 * This function duplicates a file descriptor to a specified file descriptor.
117 * This is primarily used to atomically replace a described file.
118 *
119 * @param oldfd source file descriptor to copy
120 * @param newfd destination file descriptor to replace
121 *
122 * @note Contrary to standard dup2(), the new file descriptor has the
123 * close-on-exec descriptor flag preset.
124 *
125 * @retval newfd success
126 * @retval -1 failure (see @c errno)
127 */
128VLC_API int vlc_dup2(int oldfd, int newfd);
129
130/**
131 * Creates a pipe (see "man pipe" for further reference). The new file
132 * descriptors have the close-on-exec flag preset.
133 * @return 0 on success, -1 on error (see errno)
134 */
135VLC_API int vlc_pipe(int [2]) VLC_USED;
136
137/**
138 * Creates an anonymous regular file descriptor, i.e. a descriptor for a
139 * temporary file.
140 *
141 * The file is initially empty. The storage space is automatically reclaimed
142 * when all file descriptors referencing it are closed.
143 *
144 * The new file descriptor has the close-on-exec flag preset.
145 *
146 * @return a file descriptor on success, -1 on error (see errno)
147 */
148VLC_API int vlc_memfd(void) VLC_USED;
149
150/**
151 * Writes data to a file descriptor. Unlike write(), if EPIPE error occurs,
152 * this function does not generate a SIGPIPE signal.
153 * @note If the file descriptor is known to be neither a pipe/FIFO nor a
154 * connection-oriented socket, the normal write() should be used.
155 */
156VLC_API ssize_t vlc_write(int, const void *, size_t);
157
158/**
159 * Writes data from an iovec structure to a file descriptor. Unlike writev(),
160 * if EPIPE error occurs, this function does not generate a SIGPIPE signal.
161 */
162VLC_API ssize_t vlc_writev(int, const struct iovec *, int);
163
164/**
165 * Closes a file descriptor.
166 *
167 * This closes a file descriptor. If this is a last file descriptor for the
168 * underlying open file, the file is closed too; the exact semantics depend
169 * on the type of file.
170 *
171 * @note The file descriptor is always closed when the function returns, even
172 * if the function returns an error. The sole exception is if the file
173 * descriptor was not currently valid, and thus cannot be closed (errno will
174 * then be set to EBADF).
175 *
176 * @param fd file descriptor
177 * @return Normally, zero is returned.
178 * If an I/O error is detected before or while closing, the function may return
179 * -1. Such an error is unrecoverable since the descriptor is closed.
180 *
181 * A nul return value does not necessarily imply that all pending I/O
182 * succeeded, since I/O might still occur asynchronously afterwards.
183 */
184VLC_API int vlc_close(int fd);
185
186/**
187 * @}
188 */
189
190/**
191 * Finds file/inode information - like stat().
192 * @note As far as possible, fstat() should be used instead.
193 *
194 * @param filename UTF-8 file path
195 * @param st the POSIX stat structure to fill
196 */
197VLC_API int vlc_stat(const char *filename, struct stat *st) VLC_USED;
198
199/**
200 * Finds file/inode information, as lstat().
201 * Consider using fstat() instead, if possible.
202 *
203 * @param filename UTF-8 file path
204 * @param st the POSIX stat structure to fill
205 */
206VLC_API int vlc_lstat(const char *filename, struct stat *st) VLC_USED;
207
208/**
209 * Removes a file.
210 *
211 * @param filename a UTF-8 string with the name of the file you want to delete.
212 * @return A 0 return value indicates success. A -1 return value indicates an
213 * error, and an error code is stored in errno
214 */
215VLC_API int vlc_unlink(const char *filename);
216
217/**
218 * Moves a file atomically. This only works within a single file system.
219 *
220 * @param oldpath path to the file before the move
221 * @param newpath intended path to the file after the move
222 * @return A 0 return value indicates success. A -1 return value indicates an
223 * error, and an error code is stored in errno
224 */
225VLC_API int vlc_rename(const char *oldpath, const char *newpath);
226
227VLC_API FILE * vlc_fopen( const char *filename, const char *mode ) VLC_USED;
228
229/**
230 * \defgroup dir Directories
231 * @{
232 */
233
234#if defined( _WIN32 )
235typedef struct vlc_DIR vlc_DIR;
236#else // !_WIN32
237typedef DIR vlc_DIR;
238#endif
239
240/**
241 * Opens a DIR pointer.
242 *
243 * @param dirname UTF-8 representation of the directory name
244 * @return a pointer to the DIR struct, or NULL in case of error.
245 * Release with vlc_closedir().
246 */
247VLC_API vlc_DIR *vlc_opendir(const char *dirname) VLC_USED;
248
249/**
250 * Reads the next file name from an open directory.
251 *
252 * @param dir directory handle as returned by vlc_opendir()
253 * (must not be used by another thread concurrently)
254 *
255 * @return a UTF-8 string of the directory entry. The string is valid until
256 * the next call to vlc_readdir() or vlc_closedir() on the handle.
257 * If there are no more entries in the directory, NULL is returned.
258 * If an error occurs, errno is set and NULL is returned.
259 */
260VLC_API const char *vlc_readdir(vlc_DIR *dir) VLC_USED;
261
262VLC_API int vlc_loaddir( vlc_DIR *dir, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
263VLC_API int vlc_scandir( const char *dirname, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
264
265VLC_API void vlc_closedir( vlc_DIR *dir );
266VLC_API void vlc_rewinddir( vlc_DIR *dir );
267
268/**
269 * Creates a directory.
270 *
271 * @param dirname a UTF-8 string with the name of the directory that you
272 * want to create.
273 * @param mode directory permissions
274 * @return 0 on success, -1 on error (see errno).
275 */
276VLC_API int vlc_mkdir(const char *dirname, mode_t mode);
277
278/**
279 * Creates a directory and parent directories as needed.
280 *
281 * @param dirname a UTF-8 string containing the name of the directory to
282 * be created.
283 * @param mode directory permissions
284 * @return 0 on success, -1 on error (see errno).
285 */
286VLC_API int vlc_mkdir_parent(const char *dirname, mode_t mode);
287
288/**
289 * Determines the current working directory.
290 *
291 * @return the current working directory (must be free()'d)
292 * or NULL on error
293 */
294VLC_API char *vlc_getcwd(void) VLC_USED;
295
296/** @} */
297
298#ifdef __ANDROID__
299# define lseek lseek64
300#endif
301
302/** @} */
303#endif
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
int vlc_mkdir_parent(const char *dirname, mode_t mode)
Creates a directory and parent directories as needed.
Definition filesystem.c:20
vlc_DIR * vlc_opendir(const char *dirname)
Opens a DIR pointer.
Definition filesystem.c:110
char * vlc_getcwd(void)
Determines the current working directory.
Definition filesystem.c:228
void vlc_rewinddir(vlc_DIR *dir)
Definition filesystem.c:322
DIR vlc_DIR
Definition vlc_fs.h:238
int vlc_mkdir(const char *dirname, mode_t mode)
Creates a directory.
Definition filesystem.c:96
const char * vlc_readdir(vlc_DIR *dir)
Reads the next file name from an open directory.
Definition filesystem.c:282
int vlc_loaddir(vlc_DIR *dir, char ***namelist, int(*select)(const char *), int(*compar)(const char **, const char **))
Does the same as vlc_scandir(), but takes an open directory pointer instead of a directory path.
Definition filesystem.c:121
void vlc_closedir(vlc_DIR *dir)
Definition filesystem.c:272
int vlc_scandir(const char *dirname, char ***namelist, int(*select)(const char *), int(*compar)(const char **, const char **))
Selects file entries from a directory, as GNU C scandir().
Definition filesystem.c:189
int vlc_mkstemp(char *)
Definition filesystem.c:206
int vlc_open(const char *filename, int flags,...)
Opens a system file handle.
Definition filesystem.c:52
int vlc_pipe(int[2])
Creates a pipe (see "man pipe" for further reference).
Definition filesystem.c:285
int vlc_openat(int dir, const char *filename, int flags,...)
Opens a system file handle relative to an existing directory handle.
Definition filesystem.c:78
int vlc_memfd(void)
Creates an anonymous regular file descriptor, i.e.
Definition filesystem.c:38
int vlc_dup2(int oldfd, int newfd)
Replaces a file descriptor.
Definition filesystem.c:276
ssize_t vlc_writev(int, const struct iovec *, int)
Writes data from an iovec structure to a file descriptor.
Definition filesystem.c:306
int vlc_dup(int oldfd)
Duplicates a file descriptor.
Definition filesystem.c:265
int vlc_close(int fd)
Closes a file descriptor.
Definition filesystem.c:91
ssize_t vlc_write(int, const void *, size_t)
Writes data to a file descriptor.
Definition filesystem.c:299
int vlc_stat(const char *filename, struct stat *st)
Finds file/inode information - like stat().
Definition filesystem.c:183
int vlc_lstat(const char *filename, struct stat *st)
Finds file/inode information, as lstat().
Definition filesystem.c:188
int vlc_rename(const char *oldpath, const char *newpath)
Moves a file atomically.
Definition filesystem.c:207
int vlc_unlink(const char *filename)
Removes a file.
Definition filesystem.c:193
FILE * vlc_fopen(const char *filename, const char *mode)
Opens a FILE pointer.
Definition filesystem.c:49
int(* compar)(const void *, const void *, void *)
Definition sort.c:31
Definition filesystem.c:156
This file is a collection of common definitions and types.