Skip to content

V
vlc
Commit 3244a744 authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont
Browse files
Options

filesystem: clean up documentation

parent 62e03dd8
Show whitespace changes
Inline Side-by-side
Showing with 152 additions and 231 deletions
include/vlc_fs.h
View file @ 3244a744
......@@ -21,7 +21,18 @@
#ifndef VLC_FS_H
#define VLC_FS_H 1
#include <sys/types.h>
#include <dirent.h>
struct stat;
struct iovec;
/**
* \defgroup os Operating system
* @{
* \defgroup file File system
* @{
*
* \file
* The functions in this file help with using low-level Unix-style file
* descriptors, BSD sockets and directories. In general, they retain the
......@@ -38,24 +49,155 @@
* - vlc_accept() takes an extra boolean for nonblocking mode (compare with
* the flags parameter in POSIX.next accept4()).
* - Writing functions do not emit a SIGPIPE signal in case of broken pipe.
*
* \defgroup fd File descriptors
* @{
*/
#include <sys/types.h>
#include <dirent.h>
/**
* Opens a system file handle.
*
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns a file handle
* with the close-on-exec flag preset.
*/
VLC_API int vlc_open(const char *filename, int flags, ...) VLC_USED;
/**
* Opens a system file handle relative to an existing directory handle.
*
* @param dir directory file descriptor
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns a file handle
* with the close-on-exec flag preset.
*/
VLC_API int vlc_openat(int fd, const char *filename, int flags, ...) VLC_USED;
VLC_API int vlc_mkstemp( char * );
/**
* Duplicates a file descriptor. The new file descriptor has the close-on-exec
* descriptor flag preset.
* @return a new file descriptor, -1 (see errno)
*/
VLC_API int vlc_dup(int) VLC_USED;
/**
* Creates a pipe (see "man pipe" for further reference). The new file
* descriptors have the close-on-exec flag preset.
* @return 0 on success, -1 on error (see errno)
*/
VLC_API int vlc_pipe(int [2]) VLC_USED;
/**
* Writes data to a file descriptor. Unlike write(), if EPIPE error occurs,
* this function does not generate a SIGPIPE signal.
* @note If the file descriptor is known to be neither a pipe/FIFO nor a
* connection-oriented socket, the normal write() should be used.
*/
VLC_API ssize_t vlc_write(int, const void *, size_t);
/**
* Writes data from an iovec structure to a file descriptor. Unlike writev(),
* if EPIPE error occurs, this function does not generate a SIGPIPE signal.
*/
VLC_API ssize_t vlc_writev(int, const struct iovec *, int);
/**
* @}
*/
/**
* Finds file/inode information - like stat().
* @note As far as possible, fstat() should be used instead.
*
* @param filename UTF-8 file path
*/
VLC_API int vlc_stat(const char *filename, struct stat *) VLC_USED;
/**
* Finds file/inode information, as lstat().
* Consider using fstat() instead, if possible.
*
* @param filename UTF-8 file path
*/
VLC_API int vlc_lstat(const char *filename, struct stat *) VLC_USED;
/**
* Removes a file.
*
* @param filename a UTF-8 string with the name of the file you want to delete.
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
VLC_API int vlc_unlink(const char *filename);
/**
* Moves a file atomically. This only works within a single file system.
*
* @param oldpath path to the file before the move
* @param newpath intended path to the file after the move
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
VLC_API int vlc_rename(const char *oldpath, const char *newpath);
VLC_API int vlc_open( const char *filename, int flags, ... ) VLC_USED;
VLC_API FILE * vlc_fopen( const char *filename, const char *mode ) VLC_USED;
VLC_API int vlc_openat( int fd, const char *filename, int flags, ... ) VLC_USED;
VLC_API DIR * vlc_opendir( const char *dirname ) VLC_USED;
VLC_API char * vlc_readdir( DIR *dir ) VLC_USED;
/**
* \defgroup dir Directories
* @{
*/
/**
* Opens a DIR pointer.
*
* @param dirname UTF-8 representation of the directory name
* @return a pointer to the DIR struct, or NULL in case of error.
* Release with standard closedir().
*/
VLC_API DIR *vlc_opendir(const char *dirname) VLC_USED;
/**
* Reads the next file name from an open directory.
*
* @param dir directory handle as returned by vlc_opendir()
* (must not be used by another thread concurrently)
*
* @return a UTF-8 string of the directory entry. The string is valid until
* the next call to vlc_readdir() or closedir() on the handle.
* If there are no more entries in the directory, NULL is returned.
* If an error occurs, errno is set and NULL is returned.
*/
VLC_API char *vlc_readdir(DIR *dir) VLC_USED;
VLC_API int vlc_loaddir( DIR *dir, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
VLC_API int vlc_scandir( const char *dirname, char ***namelist, int (*select)( const char * ), int (*compar)( const char **, const char ** ) );
VLC_API int vlc_mkdir( const char *filename, mode_t mode );
VLC_API int vlc_unlink( const char *filename );
VLC_API int vlc_rename( const char *oldpath, const char *newpath );
VLC_API char *vlc_getcwd( void ) VLC_USED;
/**
* Creates a directory.
*
* @param dirname a UTF-8 string with the name of the directory that you
* want to create.
* @param mode directory permissions
* @return 0 on success, -1 on error (see errno).
*/
VLC_API int vlc_mkdir(const char *dirname, mode_t mode);
/**
* Determines the current working directory.
*
* @return the current working directory (must be free()'d)
* or NULL on error
*/
VLC_API char *vlc_getcwd(void) VLC_USED;
/** @} */
/** @} */
#if defined( _WIN32 )
typedef struct vlc_DIR
......@@ -107,16 +249,4 @@ static inline void vlc_rewinddir( DIR *dir )
# define lseek lseek64
#endif
struct stat;
struct iovec;
VLC_API int vlc_stat( const char *filename, struct stat *buf );
VLC_API int vlc_lstat( const char *filename, struct stat *buf );
VLC_API int vlc_mkstemp( char * );
VLC_API int vlc_dup( int );
VLC_API int vlc_pipe( int[2] );
VLC_API ssize_t vlc_write( int, const void *, size_t );
VLC_API ssize_t vlc_writev( int, const struct iovec *, int );
#endif
src/os2/filesystem.c
View file @ 3244a744
......@@ -46,15 +46,6 @@
#include <vlc_fs.h>
#include "libvlc.h" /* vlc_mkdir */
/**
* Opens a system file handle.
*
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns file handles
* with the close-on-exec flag enabled.
*/
int vlc_open (const char *filename, int flags, ...)
{
unsigned int mode = 0;
......@@ -81,16 +72,6 @@ int vlc_open (const char *filename, int flags, ...)
return fd;
}
/**
* Opens a system file handle relative to an existing directory handle.
*
* @param dir directory file descriptor
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns file handles
* with the close-on-exec flag enabled.
*/
int vlc_openat (int dir, const char *filename, int flags, ...)
{
errno = ENOSYS;
......@@ -98,15 +79,6 @@ int vlc_openat (int dir, const char *filename, int flags, ...)
return -1;
}
/**
* Creates a directory using UTF-8 paths.
*
* @param dirname a UTF-8 string with the name of the directory that you
* want to create.
* @param mode directory permissions
* @return 0 on success, -1 on error (see errno).
*/
int vlc_mkdir (const char *dirname, mode_t mode)
{
char *locname = ToLocaleDup (dirname);
......@@ -121,13 +93,6 @@ int vlc_mkdir (const char *dirname, mode_t mode)
return res;
}
/**
* Opens a DIR pointer.
*
* @param dirname UTF-8 representation of the directory name
* @return a pointer to the DIR struct, or NULL in case of error.
* Release with standard closedir().
*/
DIR *vlc_opendir (const char *dirname)
{
const char *locname = ToLocaleDup (dirname);
......@@ -144,15 +109,6 @@ DIR *vlc_opendir (const char *dirname)
return dir;
}
/**
* Reads the next file name from an open directory.
*
* @param dir The directory that is being read
*
* @return a UTF-8 string of the directory entry. Use free() to release it.
* If there are no more entries in the directory, NULL is returned.
* If an error occurs, errno is set and NULL is returned.
*/
char *vlc_readdir( DIR *dir )
{
/* Beware that readdir_r() assumes <buf> is large enough to hold the result
......@@ -200,35 +156,16 @@ static int vlc_statEx (const char *filename, struct stat *buf, bool deref)
return res;
}
/**
* Finds file/inode information, as stat().
* Consider using fstat() instead, if possible.
*
* @param filename UTF-8 file path
*/
int vlc_stat (const char *filename, struct stat *buf)
{
return vlc_statEx (filename, buf, true);
}
/**
* Finds file/inode information, as lstat().
* Consider using fstat() instead, if possible.
*
* @param filename UTF-8 file path
*/
int vlc_lstat (const char *filename, struct stat *buf)
{
return vlc_statEx (filename, buf, false);
}
/**
* Removes a file.
*
* @param filename a UTF-8 string with the name of the file you want to delete.
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
int vlc_unlink (const char *filename)
{
const char *local_name = ToLocaleDup (filename);
......@@ -243,14 +180,6 @@ int vlc_unlink (const char *filename)
return ret;
}
/**
* Moves a file atomically. This only works within a single file system.
*
* @param oldpath path to the file before the move
* @param newpath intended path to the file after the move
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
int vlc_rename (const char *oldpath, const char *newpath)
{
const char *lo = ToLocaleDup (oldpath);
......@@ -272,12 +201,6 @@ error:
return ret;
}
/**
* Determines the current working directory.
*
* @return the current working directory (must be free()'d)
* or NULL on error
*/
char *vlc_getcwd (void)
{
/* Try $PWD */
......@@ -315,11 +238,6 @@ char *vlc_getcwd (void)
return NULL;
}
/**
* Duplicates a file descriptor. The new file descriptor has the close-on-exec
* descriptor flag set.
* @return a new file descriptor or -1
*/
int vlc_dup (int oldfd)
{
int newfd;
......@@ -331,9 +249,6 @@ int vlc_dup (int oldfd)
return newfd;
}
/**
* Creates a pipe (see "man pipe" for further reference).
*/
int vlc_pipe (int fds[2])
{
if (pipe (fds))
......@@ -347,12 +262,6 @@ int vlc_pipe (int fds[2])
return 0;
}
/**
* Writes data to a file descriptor. Unlike write(), if EPIPE error occurs,
* this function does not generate a SIGPIPE signal.
* @note If the file descriptor is known to be neither a pipe/FIFO nor a
* connection-oriented socket, the normal write() should be used.
*/
ssize_t vlc_write(int fd, const void *buf, size_t len)
{
struct iovec iov = { .iov_base = (void *)buf, .iov_len = len };
......@@ -360,10 +269,6 @@ ssize_t vlc_write(int fd, const void *buf, size_t len)
return vlc_writev(fd, &iov, 1);
}
/**
* Writes data from an iovec structure to a file descriptor. Unlike writev(),
* if EPIPE error occurs, this function does not generate a SIGPIPE signal.
*/
ssize_t vlc_writev(int fd, const struct iovec *iov, int count)
{
sigset_t set, oset;
......@@ -389,15 +294,6 @@ ssize_t vlc_writev(int fd, const struct iovec *iov, int count)
#include <vlc_network.h>
/**
* Creates a socket file descriptor. The new file descriptor has the
* close-on-exec flag set.
* @param pf protocol family
* @param type socket type
* @param proto network protocol
* @param nonblock true to create a non-blocking socket
* @return a new file descriptor or -1
*/
int vlc_socket (int pf, int type, int proto, bool nonblock)
{
int fd;
......@@ -412,15 +308,6 @@ int vlc_socket (int pf, int type, int proto, bool nonblock)
return fd;
}
/**
* Accepts an inbound connection request on a listening socket.
* The new file descriptor has the close-on-exec flag set.
* @param lfd listening socket file descriptor
* @param addr pointer to the peer address or NULL [OUT]
* @param alen pointer to the length of the peer address or NULL [OUT]
* @param nonblock whether to put the new socket in non-blocking mode
* @return a new file descriptor, or -1 on error.
*/
int vlc_accept (int lfd, struct sockaddr *addr, socklen_t *alen, bool nonblock)
{
do
......
src/posix/filesystem.c
View file @ 3244a744
......@@ -47,15 +47,6 @@
#include <vlc_fs.h>
#include "libvlc.h" /* vlc_mkdir */
/**
* Opens a system file handle.
*
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns file handles
* with the close-on-exec flag enabled.
*/
int vlc_open (const char *filename, int flags, ...)
{
unsigned int mode = 0;
......@@ -76,16 +67,6 @@ int vlc_open (const char *filename, int flags, ...)
return fd;
}
/**
* Opens a system file handle relative to an existing directory handle.
*
* @param dir directory file descriptor
* @param filename file path to open (with UTF-8 encoding)
* @param flags open() flags, see the C library open() documentation
* @return a file handle on success, -1 on error (see errno).
* @note Contrary to standard open(), this function returns file handles
* with the close-on-exec flag enabled.
*/
int vlc_openat (int dir, const char *filename, int flags, ...)
{
unsigned int mode = 0;
......@@ -116,101 +97,42 @@ int vlc_openat (int dir, const char *filename, int flags, ...)
}
/**
* Creates a directory using UTF-8 paths.
*
* @param dirname a UTF-8 string with the name of the directory that you
* want to create.
* @param mode directory permissions
* @return 0 on success, -1 on error (see errno).
*/
int vlc_mkdir (const char *dirname, mode_t mode)
{
return mkdir (dirname, mode);
}
/**
* Opens a DIR pointer.
*
* @param dirname UTF-8 representation of the directory name
* @return a pointer to the DIR struct, or NULL in case of error.
* Release with standard closedir().
*/
DIR *vlc_opendir (const char *dirname)
{
return opendir (dirname);
}
/**
* Reads the next file name from an open directory.
*
* @param dir directory handle as returned by vlc_opendir()
* (must not be used by another thread concurrently)
*
* @return a UTF-8 string of the directory entry. The string is valid until
* the next call to vlc_readdir() or closedir() on the handle.
* If there are no more entries in the directory, NULL is returned.
* If an error occurs, errno is set and NULL is returned.
*/
char *vlc_readdir( DIR *dir )
{
struct dirent *ent = readdir (dir);
return (ent != NULL) ? ent->d_name : NULL;
}
/**
* Finds file/inode information, as stat().
* Consider using fstat() instead, if possible.
*
* @param filename UTF-8 file path
*/
int vlc_stat (const char *filename, struct stat *buf)
{
return stat (filename, buf);
}
/**
* Finds file/inode information, as lstat().
* Consider using fstat() instead, if possible.
*
* @param filename UTF-8 file path
*/
int vlc_lstat (const char *filename, struct stat *buf)
{
return lstat (filename, buf);
}
/**
* Removes a file.
*
* @param filename a UTF-8 string with the name of the file you want to delete.
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
int vlc_unlink (const char *filename)
{
return unlink (filename);
}
/**
* Moves a file atomically. This only works within a single file system.
*
* @param oldpath path to the file before the move
* @param newpath intended path to the file after the move
* @return A 0 return value indicates success. A -1 return value indicates an
* error, and an error code is stored in errno
*/
int vlc_rename (const char *oldpath, const char *newpath)
{
return rename (oldpath, newpath);
}
/**
* Determines the current working directory.
*
* @return the current working directory (must be free()'d)
* or NULL on error
*/
char *vlc_getcwd (void)
{
long path_max = pathconf (".", _PC_PATH_MAX);
......@@ -232,11 +154,6 @@ char *vlc_getcwd (void)
return NULL;
}
/**
* Duplicates a file descriptor. The new file descriptor has the close-on-exec
* descriptor flag set.
* @return a new file descriptor or -1
*/
int vlc_dup (int oldfd)
{
int newfd;
......@@ -253,9 +170,6 @@ int vlc_dup (int oldfd)
return newfd;
}
/**
* Creates a pipe (see "man pipe" for further reference).
*/
int vlc_pipe (int fds[2])
{
#ifdef HAVE_PIPE2
......@@ -273,12 +187,6 @@ int vlc_pipe (int fds[2])
return 0;
}
/**
* Writes data to a file descriptor. Unlike write(), if EPIPE error occurs,
* this function does not generate a SIGPIPE signal.
* @note If the file descriptor is known to be neither a pipe/FIFO nor a
* connection-oriented socket, the normal write() should be used.
*/
ssize_t vlc_write(int fd, const void *buf, size_t len)
{
struct iovec iov = { .iov_base = (void *)buf, .iov_len = len };
......@@ -286,10 +194,6 @@ ssize_t vlc_write(int fd, const void *buf, size_t len)
return vlc_writev(fd, &iov, 1);
}
/**
* Writes data from an iovec structure to a file descriptor. Unlike writev(),
* if EPIPE error occurs, this function does not generate a SIGPIPE signal.
*/
ssize_t vlc_writev(int fd, const struct iovec *iov, int count)
{
sigset_t set, oset;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment