exit syscall (#295)

* exit syscall

* exit-syscall changes

* warnings addressed

* removed decrement def

* removed decrement df

* comments resolved

---------

Co-authored-by: lind <lind@nyu.edu>

Author: Anway-Agte

src/safeposix/syscalls/sys_calls.rs

@@ -248,7 +248,7 @@ impl Cage {
                     Socket(socket_filedesc_obj) => {
                         // Check if it is a domain socket
                         let sock_tmp = socket_filedesc_obj.handle.clone();
-                        let mut sockhandle = sock_tmp.write();
+                        let sockhandle = sock_tmp.write();
                         let socket_type = sockhandle.domain;
                         //Here we only increment the reference for AF_UNIX socket type
                         //Since these are the only sockets that have an inode associated with them
@@ -483,33 +483,61 @@ impl Cage {
         0
     }
 
+    /// ### Description
+    /// 
+    /// The exit function causes normal process(Cage) termination
+    /// The termination entails unmapping all memory references
+    /// Removing the cage object from the cage table, closing all open files
+    /// And decrement all references to files and directories
+    /// For more information please refer [https://man7.org/linux/man-pages/man3/exit.3.html]
+    /// 
+    /// ### Arguments 
+    /// 
+    /// The exit function takes only one argument which is `status`
+    /// `status` : This is a 32 bit integer value that the function returns back 
+    /// upon sucessfully terminating the process
+    /// 
+    /// ### Returns
+    /// 
+    /// This function returns a 32 bit integer value - which represents succesful 
+    /// termination of the calling Cage object
+    /// 
+    /// ### Panics
+    /// 
+    /// While this syscall does not panic directly - it can panic if the 
+    /// `decref_dir` function panics - which occurs when the working directory
+    /// passed to it is not a valid directory or the directory did not exist at all. 
+    /// or if the cage_id passed to the remove function is not a valid cage id. 
+    /// 
+    /// ### Errors
+    /// 
+    /// This function has no scenario where it returns an error
     pub fn exit_syscall(&self, status: i32) -> i32 {
-        //flush anything left in stdout
+        //Clear all values in stdout stream
         interface::flush_stdout();
-
+        //Unmap all memory mappings for the current cage object
         self.unmap_shm_mappings();
 
-        // close fds
+        //For all file descriptors that the cage holds
         for fd in 0..MAXFD {
+            // Close the file pointed to by the file descriptor
             self._close_helper(fd);
         }
 
-        //get file descriptor table into a vector
-        let cwd_container = self.cwd.read();
-
-        //may not be removable in case of lindrustfinalize, we don't unwrap the remove
-        // result
+        //Remove the current cage object from the cage table
         interface::cagetable_remove(self.cageid);
 
-        // Trigger SIGCHLD
+        // Check if Lind is being run as a test suite or not
+        // We do this since we only want to 
         if !interface::RUSTPOSIX_TESTSUITE.load(interface::RustAtomicOrdering::Relaxed) {
-            // dont trigger SIGCHLD for test suite
+            // Trigger SIGCHILD if LIND is not run as a test suite
+            // SIGCHILD is simply a response that the parent recieves when it's child process terminates
             if self.cageid != self.parent {
                 interface::lind_kill_from_id(self.parent, SIGCHLD);
             }
         }
 
-        //fdtable will be dropped at end of dispatcher scope because of Arc
+        // Return the status integer back to the calling function
         status
     }
 

src/tests/sys_tests.rs

@@ -90,5 +90,16 @@ pub mod test_sys {
         assert_eq!(child_cage.cwd.read(),cage.cwd.read())
     }
 
+    pub fn ut_lind_exit() {
+        // Since exit function is heavily used and tested in other syscalls and their tests 
+        // We only perform preliminary checks for checking the sanity of this syscall
+        // We don't check for cases such as exiting a cage twice - since the exiting process 
+        // is handled by the NaCl runtime - and it ensures that a cage does not exit twice
+        lindrustinit(0);
+        let cage = interface::cagetable_getref(1);
+        // Call the exit call
+        assert_eq(cage.exit_syscall(EXIT_SUCCESS),EXIT_SUCCESS); 
+        lindrustfinalize(); 
+    }
 }