[vlc-devel] [PATCH v3 7/14] fs: document vlc_mkstemp()

[Lyndon Brown]

From: Lyndon Brown <jnqnfe at gmail.com>
Date: Thu, 8 Oct 2020 01:31:31 +0100
Subject: fs: document vlc_mkstemp()


diff --git a/include/vlc_fs.h b/include/vlc_fs.h
index f3f50ea431..e6cee45fd1 100644
--- a/include/vlc_fs.h
+++ b/include/vlc_fs.h
@@ -97,6 +97,23 @@ VLC_API int vlc_open(const char *filename, int flags, ...) VLC_USED;
  */
 VLC_API int vlc_openat(int fd, const char *filename, int flags, ...) VLC_USED;
 
+/**
+ * Cross-platform mkstemp implementation for temporary file creation.
+ *
+ * Uses actual mkstemp where available (see its documentation for full details),
+ * otherwise a reimplementation. Creates and opens a unique file securely
+ * (using O_EXCL) in O_RDWR mode, returning the file descriptor and modifying
+ * the provided template with the actual filename of the created file.
+ *
+ * The provided `template` parameter should include the directory in which to
+ * create the file (which should already exist), unless the file is to be
+ * created in the CWD. It must include the filename which **MUST** end in
+ * XXXXXX, which will be replaced with a unique pattern. The provided string
+ * will be modified to thus return the actual filename of the created file.
+ *
+ * @param template the path and filename template of the file to create.
+ * @return a file handle on success, -1 on error.
+ */
 VLC_API int vlc_mkstemp( char * );
 
 /**