docs: Process and User identification

Add more details to Process and User identification section.

1 files changed, 43 insertions, 1 deletions

diff --git a/luxio.c b/luxio.c
index 205cc92..7699051 100644
--- a/luxio.c
+++ b/luxio.c
@@ -525,6 +525,9 @@ luxio_sleep(lua_State *L) /* 3.4.3 */
 */
 
 /*** Get process identification.
+
+Returns the process ID of the calling process.
+
 @treturn number pid
 @function getpid
 */
@@ -537,6 +540,9 @@ luxio_getpid(lua_State *L) /* 4.1.1 */
 }
 
 /*** Get process's parent's identification.
+
+Returns the process ID of the parent of calling process
+
 @treturn number pid
 @function getppid
 */
@@ -553,6 +559,9 @@ luxio_getppid(lua_State *L) /* 4.1.1 */
 */
 
 /*** Get user identity.
+
+Returns the real user ID of the calling process.
+
 @treturn number uid
 @function getuid
 */
@@ -565,6 +574,9 @@ luxio_getuid(lua_State *L) /* 4.2.1 */
 }
 
 /*** Get effective user identity.
+
+Returns the effective user ID of the calling process.
+
 @treturn number uid
 @function geteuid
 */
@@ -577,6 +589,9 @@ luxio_geteuid(lua_State *L) /* 4.2.1 */
 }
 
 /*** Get group identity.
+
+Returns the real group ID of the calling process.
+
 @treturn number gid
 @function getgid
 */
@@ -589,6 +604,9 @@ luxio_getgid(lua_State *L) /* 4.2.1 */
 }
 
 /*** Get effective group identity.
+
+Returns the effective group ID of the calling process
+
 @treturn number gid
 @function getegid
 */
@@ -601,6 +619,16 @@ luxio_getegid(lua_State *L) /* 4.2.1 */
 }
 
 /*** Set user identity.
+
+Set the effective user ID of the calling process.
+If the effective UID of the caller is root the real UID and
+saved set-user-ID are also set.
+
+Returns zero on success. Returns -1 on failure, with errno set appropriately.
+
+__`setuid()` can fail even when the caller is UID 0,
+   it is a grave security error to fail to check return value of `setuid().`__
+
 @tparam number uid
 @treturn number return value
 @treturn errno errno
@@ -617,7 +645,14 @@ luxio_setuid(lua_State *L) /* 4.2.2 */
 	return 2;
 }
 
-/*** Set group identity
+/*** Set group identity.
+
+Set the effective group ID of the calling process.
+If the caller is the superuser, the real GID and saved set-group-ID
+are also set.
+
+Returns zero on success. Returns -1 on failure, with errno set appropriately.
+
 @tparam number gid
 @treturn number return value
 @treturn errno errno
@@ -637,6 +672,13 @@ luxio_setgid(lua_State *L) /* 4.2.2 */
 /* TODO: getgroups() 4.2.3 */
 
 /*** Get username.
+
+Returns 0 on success and non-zero on failure.
+
+On success the second return value contains the name of the user logged in on
+the process's controlling terminal. On failure the second return value
+contains errno.
+
 @treturn number return value
 @treturn string|errno username or errno
 @function getlogin