1 /*****************************************************************************
2 * vlc_fs.h: File system helpers
3 *****************************************************************************
4 * Copyright © 2006-2010 Rémi Denis-Courmont
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.
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.
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 *****************************************************************************/
24 #include <sys/types.h>
31 # include <sys/stat.h>
33 # define stat _stati64
36 # define fstat _fstati64
40 # define lseek _lseeki64
45 # define lseek lseek64
50 * \defgroup os Operating system
52 * \defgroup file File system
56 * The functions in this file help with using low-level Unix-style file
57 * descriptors, BSD sockets and directories. In general, they retain the
58 * prototype and most semantics from their respective standard equivalents.
59 * However, there are a few differences:
60 * - On Windows, file path arguments are expected in UTF-8 format.
61 * They are converted to UTF-16 internally, thus enabling access to paths
62 * outside of the local Windows ANSI code page.
63 * - On POSIX systems, file descriptors are created with the close-on-exec
64 * flag set (atomically where possible), so that they do not leak to
65 * child process after fork-and-exec.
66 * - vlc_scandir(), inspired by GNU scandir(), passes file names rather than
67 * dirent structure pointers to its callbacks.
68 * - vlc_accept() takes an extra boolean for nonblocking mode (compare with
69 * the flags parameter in POSIX.next accept4()).
70 * - Writing functions do not emit a SIGPIPE signal in case of broken pipe.
72 * \defgroup fd File descriptors
77 * Opens a system file handle.
79 * @param filename file path to open (with UTF-8 encoding)
80 * @param flags open() flags, see the C library open() documentation
81 * @return a file handle on success, -1 on error (see errno).
82 * @note Contrary to standard open(), this function returns a file handle
83 * with the close-on-exec flag preset.
85 VLC_API
int vlc_open(const char *filename
, int flags
, ...) VLC_USED
;
88 * Opens a system file handle relative to an existing directory handle.
90 * @param dir directory file descriptor
91 * @param filename file path to open (with UTF-8 encoding)
92 * @param flags open() flags, see the C library open() documentation
93 * @return a file handle on success, -1 on error (see errno).
94 * @note Contrary to standard open(), this function returns a file handle
95 * with the close-on-exec flag preset.
97 VLC_API
int vlc_openat(int fd
, const char *filename
, int flags
, ...) VLC_USED
;
99 VLC_API
int vlc_mkstemp( char * );
102 * Duplicates a file descriptor. The new file descriptor has the close-on-exec
103 * descriptor flag preset.
104 * @return a new file descriptor, -1 (see errno)
106 VLC_API
int vlc_dup(int) VLC_USED
;
109 * Creates a pipe (see "man pipe" for further reference). The new file
110 * descriptors have the close-on-exec flag preset.
111 * @return 0 on success, -1 on error (see errno)
113 VLC_API
int vlc_pipe(int [2]) VLC_USED
;
116 * Creates an anonymous regular file descriptor, i.e. a descriptor for a
119 * The file is initially empty. The storage space is automatically reclaimed
120 * when all file descriptors referencing it are closed.
122 * The new file descriptor has the close-on-exec flag preset.
124 * @return a file descriptor on success, -1 on error (see errno)
126 VLC_API
int vlc_memfd(void) VLC_USED
;
129 * Writes data to a file descriptor. Unlike write(), if EPIPE error occurs,
130 * this function does not generate a SIGPIPE signal.
131 * @note If the file descriptor is known to be neither a pipe/FIFO nor a
132 * connection-oriented socket, the normal write() should be used.
134 VLC_API ssize_t
vlc_write(int, const void *, size_t);
137 * Writes data from an iovec structure to a file descriptor. Unlike writev(),
138 * if EPIPE error occurs, this function does not generate a SIGPIPE signal.
140 VLC_API ssize_t
vlc_writev(int, const struct iovec
*, int);
143 * Closes a file descriptor.
145 * This closes a file descriptor. If this is a last file descriptor for the
146 * underlying open file, the file is closed too; the exact semantics depend
147 * on the type of file.
149 * @note The file descriptor is always closed when the function returns, even
150 * if the function returns an error. The sole exception is if the file
151 * descriptor was not currently valid, and thus cannot be closed (errno will
152 * then be set to EBADF).
154 * @param fd file descriptor
155 * @return Normally, zero is returned.
156 * If an I/O error is detected before or while closing, the function may return
157 * -1. Such an error is unrecoverable since the descriptor is closed.
159 * A nul return value does not necessarily imply that all pending I/O
160 * succeeded, since I/O might still occur asynchronously afterwards.
162 VLC_API
int vlc_close(int fd
);
169 * Finds file/inode information - like stat().
170 * @note As far as possible, fstat() should be used instead.
172 * @param filename UTF-8 file path
174 VLC_API
int vlc_stat(const char *filename
, struct stat
*) VLC_USED
;
177 * Finds file/inode information, as lstat().
178 * Consider using fstat() instead, if possible.
180 * @param filename UTF-8 file path
182 VLC_API
int vlc_lstat(const char *filename
, struct stat
*) VLC_USED
;
187 * @param filename a UTF-8 string with the name of the file you want to delete.
188 * @return A 0 return value indicates success. A -1 return value indicates an
189 * error, and an error code is stored in errno
191 VLC_API
int vlc_unlink(const char *filename
);
194 * Moves a file atomically. This only works within a single file system.
196 * @param oldpath path to the file before the move
197 * @param newpath intended path to the file after the move
198 * @return A 0 return value indicates success. A -1 return value indicates an
199 * error, and an error code is stored in errno
201 VLC_API
int vlc_rename(const char *oldpath
, const char *newpath
);
203 VLC_API
FILE * vlc_fopen( const char *filename
, const char *mode
) VLC_USED
;
206 * \defgroup dir Directories
211 * Opens a DIR pointer.
213 * @param dirname UTF-8 representation of the directory name
214 * @return a pointer to the DIR struct, or NULL in case of error.
215 * Release with standard closedir().
217 VLC_API
DIR *vlc_opendir(const char *dirname
) VLC_USED
;
220 * Reads the next file name from an open directory.
222 * @param dir directory handle as returned by vlc_opendir()
223 * (must not be used by another thread concurrently)
225 * @return a UTF-8 string of the directory entry. The string is valid until
226 * the next call to vlc_readdir() or closedir() on the handle.
227 * If there are no more entries in the directory, NULL is returned.
228 * If an error occurs, errno is set and NULL is returned.
230 VLC_API
const char *vlc_readdir(DIR *dir
) VLC_USED
;
232 VLC_API
int vlc_loaddir( DIR *dir
, char ***namelist
, int (*select
)( const char * ), int (*compar
)( const char **, const char ** ) );
233 VLC_API
int vlc_scandir( const char *dirname
, char ***namelist
, int (*select
)( const char * ), int (*compar
)( const char **, const char ** ) );
236 * Creates a directory.
238 * @param dirname a UTF-8 string with the name of the directory that you
240 * @param mode directory permissions
241 * @return 0 on success, -1 on error (see errno).
243 VLC_API
int vlc_mkdir(const char *dirname
, mode_t mode
);
246 * Determines the current working directory.
248 * @return the current working directory (must be free()'d)
251 VLC_API
char *vlc_getcwd(void) VLC_USED
;
256 #if defined( _WIN32 )
257 typedef struct vlc_DIR
259 _WDIR
*wdir
; /* MUST be first, see <vlc_fs.h> */
268 static inline int vlc_closedir( DIR *dir
)
270 vlc_DIR
*vdir
= (vlc_DIR
*)dir
;
271 _WDIR
*wdir
= vdir
->wdir
;
275 return (wdir
!= NULL
) ? _wclosedir( wdir
) : 0;
278 # define closedir vlc_closedir
280 static inline void vlc_rewinddir( DIR *dir
)
282 _WDIR
*wdir
= *(_WDIR
**)dir
;
287 # define rewinddir vlc_rewinddir
291 # define lseek lseek64