[vlc-commits] include: improve vlc_fs.h documentation

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Thu May 14 17:29:58 2015 +0300| [128a1f1724faeac711f45863a68ac6ce325e07c1] | committer: Rémi Denis-Courmont

include: improve vlc_fs.h documentation

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=128a1f1724faeac711f45863a68ac6ce325e07c1
---

 include/vlc_fs.h |   17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/include/vlc_fs.h b/include/vlc_fs.h
index 533aa9b..4786a2e 100644
--- a/include/vlc_fs.h
+++ b/include/vlc_fs.h
@@ -23,9 +23,20 @@
 
 /**
  * \file
- * Those functions convert file paths from UTF-8 to the system-specific
- * encoding (especially UTF-16 on Windows). Also, they always mark file
- * descriptor with the close-on-exec flag.
+ * The functions in this file help with using low-level Unix-style file
+ * descriptors, BSD sockets and directories. In general, they retain the
+ * prototype and most semantics from their respective standard equivalents.
+ * However, there are a few differences:
+ *  - On Windows, file path arguments are expected in UTF-8 format.
+ *    They are converted to UTF-16 internally, thus enabling access to paths
+ *    outside of the local Windows ANSI code page.
+ *  - On POSIX systems, file descriptors are created with the close-on-exec
+ *    flag set (atomically where possible), so that they do not leak to
+ *    child process after fork-and-exec.
+ *  - vlc_scandir(), inspired by GNU scandir(), passes file names rather than
+ *    dirent structure pointers to its callbacks.
+ *  - vlc_accept() takes an extra boolean for nonblocking mode (compare with
+ *    the flags parameter in POSIX.next accept4()).
  */
 
 #include <sys/types.h>