docs: Open

Add more details to the open function.

1 files changed, 52 insertions, 0 deletions

diff --git a/luxio.c b/luxio.c
index e778d07..4ba1a9b 100644
--- a/luxio.c
+++ b/luxio.c
@@ -1173,9 +1173,61 @@ luxio_getcwd(lua_State *L) /* 5.2.2 */
 */
 
 /*** Open and possibly create a file or device.
+
+Returns file descriptor on success. On error returns -1 with errno set
+appropriately.
+
+`mode` is an optional parameter that may be a bitwise OR of the following
+constants:
+
+- _Read, write and executable_
+	- `luxio.S_IRWXU` - User read, write and executable
+	- `luxio.S_IRWXG` - Group read, write and executable
+	- `luxio.S_IRWXO` - World read, write and executable
+
+- _Readable_
+	- `luxio.S_IRUSR` - User readable
+	- `luxio.S_IRGRP` - Group readable
+	- `luxio.S_IROTH` - World readable
+
+- _Writeable_
+	- `luxio.S_IWUSR` - User writeable
+	- `luxio.S_IWGRP` - Group writeable
+	- `luxio.S_IWOTH` - World writeable
+
+- _Executable_
+	- `luxio.S_IXUSR` - User executable
+	- `luxio.S_IXGRP` - Group executable
+	- `luxio.S_IXOTH` - World executable
+
+`flags` is a parameter that may be a bitwise OR of the following
+constants:
+
+- `luxio.O_RDONLY`
+- `luxio.O_WRONLY`
+- `luxio.O_RDWR`
+- `luxio.O_APPEND`
+- `luxio.O_ASYNC`
+- `luxio.O_CLOEXEC`
+- `luxio.O_CREAT`
+- `luxio.O_EXCL`
+- `luxio.O_NOCTTY`
+- `luxio.O_NONBLOCK`
+- `luxio.O_SYNC`
+- `luxio.O_TRUNC`
+- `luxio.O_DIRECT`
+- `luxio.O_NOFOLLOW`
+- `luxio.O_NOATIME`
+- `luxio.O_LARGEFILE`
+
+_Note: Not all of these constants are available on all platforms.
+Consult the `open(2)` man pages for details._
+
 @tparam string path
 @tparam number flags
 @tparam[opt] number mode, must be specified if creating.
+@treturn result File descriptor
+@treturn errno
 @function open
 */
 static int