filesystem: clean up documentation

include/vlc_fs.h

@@ -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

@@ -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

@@ -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;