include/vlc_fs.h

   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 #include <dirent.h>
  26
  27 struct stat;
  28 struct iovec;
  29
  30 #ifdef _WIN32
  31 # include <sys/stat.h>
  32 # ifndef stat
  33 #  define stat _stati64
  34 # endif
  35 # ifndef fstat
  36 #  define fstat _fstati64
  37 # endif
  38 # ifndef _MSC_VER
  39 #  undef lseek
  40 #  define lseek _lseeki64
  41 # endif
  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  */
  86 VLC_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  */
  98 VLC_API int vlc_openat(int fd, const char *filename, int flags, ...) VLC_USED;
  99
 100 VLC_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  */
 111 VLC_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  */
 128 VLC_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  */
 135 VLC_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  */
 148 VLC_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  */
 156 VLC_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  */
 162 VLC_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  */
 184 VLC_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  */
 196 VLC_API int vlc_stat(const char *filename, struct stat *) VLC_USED;
 197
 198 /**
 199  * Finds file/inode information, as lstat().
 200  * Consider using fstat() instead, if possible.
 201  *
 202  * @param filename UTF-8 file path
 203  */
 204 VLC_API int vlc_lstat(const char *filename, struct stat *) VLC_USED;
 205
 206 /**
 207  * Removes a file.
 208  *
 209  * @param filename a UTF-8 string with the name of the file you want to delete.
 210  * @return A 0 return value indicates success. A -1 return value indicates an
 211  *        error, and an error code is stored in errno
 212  */
 213 VLC_API int vlc_unlink(const char *filename);
 214
 215 /**
 216  * Moves a file atomically. This only works within a single file system.
 217  *
 218  * @param oldpath path to the file before the move
 219  * @param newpath intended path to the file after the move
 220  * @return A 0 return value indicates success. A -1 return value indicates an
 221  *        error, and an error code is stored in errno
 222  */
 223 VLC_API int vlc_rename(const char *oldpath, const char *newpath);
 224
 225 VLC_API FILE * vlc_fopen( const char *filename, const char *mode ) VLC_USED;
 226
 227 /**
 228  * \defgroup dir Directories
 229  * @{
 230  */
 231
 232 /**
 233  * Opens a DIR pointer.
 234  *
 235  * @param dirname UTF-8 representation of the directory name
 236  * @return a pointer to the DIR struct, or NULL in case of error.
 237  * Release with standard closedir().
 238  */
 239 VLC_API DIR *vlc_opendir(const char *dirname) VLC_USED;
 240
 241 /**
 242  * Reads the next file name from an open directory.
 243  *
 244  * @param dir directory handle as returned by vlc_opendir()
 245  *            (must not be used by another thread concurrently)
 246  *
 247  * @return a UTF-8 string of the directory entry. The string is valid until
 248  * the next call to vlc_readdir() or closedir() on the handle.
 249  * If there are no more entries in the directory, NULL is returned.
 250  * If an error occurs, errno is set and NULL is returned.
 251  */
 252 VLC_API const char *vlc_readdir(DIR *dir) VLC_USED;
 253
 254 VLC_API int vlc_loaddir( DIR *dir, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
 255 VLC_API int vlc_scandir( const char *dirname, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
 256
 257 /**
 258  * Creates a directory.
 259  *
 260  * @param dirname a UTF-8 string with the name of the directory that you
 261  *        want to create.
 262  * @param mode directory permissions
 263  * @return 0 on success, -1 on error (see errno).
 264  */
 265 VLC_API int vlc_mkdir(const char *dirname, mode_t mode);
 266
 267 /**
 268  * Determines the current working directory.
 269  *
 270  * @return the current working directory (must be free()'d)
 271  *         or NULL on error
 272  */
 273 VLC_API char *vlc_getcwd(void) VLC_USED;
 274
 275 /** @} */
 276
 277 #if defined( _WIN32 )
 278 typedef struct vlc_DIR
 279 {
 280     _WDIR *wdir; /* MUST be first, see <vlc_fs.h> */
 281     char *entry;
 282     union
 283     {
 284         DWORD drives;
 285         bool insert_dot_dot;
 286     } u;
 287 } vlc_DIR;
 288
 289 static inline int vlc_closedir( DIR *dir )
 290 {
 291     vlc_DIR *vdir = (vlc_DIR *)dir;
 292     _WDIR *wdir = vdir->wdir;
 293
 294     free( vdir->entry );
 295     free( vdir );
 296     return (wdir != NULL) ? _wclosedir( wdir ) : 0;
 297 }
 298 # undef closedir
 299 # define closedir vlc_closedir
 300
 301 static inline void vlc_rewinddir( DIR *dir )
 302 {
 303     _WDIR *wdir = *(_WDIR **)dir;
 304
 305     _wrewinddir( wdir );
 306 }
 307 # undef rewinddir
 308 # define rewinddir vlc_rewinddir
 309 #endif
 310
 311 #ifdef __ANDROID__
 312 # define lseek lseek64
 313 #endif
 314
 315 #endif