Explain the semantics of exec in more detail.

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index 11d9875ce7beabe78e2ebb8e9079d7402bb31113..60a53ee09cc6d876cb562d64be4544689e4716fc 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -301,7 +301,7 @@ regardless of what user process or kernel thread is running.  In
 Pintos, kernel virtual memory is mapped one-to-one to physical
 memory, starting at @code{PHYS_BASE}.  That is, virtual address
 @code{PHYS_BASE} accesses physical
 Pintos, kernel virtual memory is mapped one-to-one to physical
 memory, starting at @code{PHYS_BASE}.  That is, virtual address
 @code{PHYS_BASE} accesses physical

-address 0, virtual address @code{PHYS_BASE} + @t{0x1234} access
+address 0, virtual address @code{PHYS_BASE} + @t{0x1234} accesses

 physical address @t{0x1234}, and so on up to the size of the machine's
 physical memory.
 
 physical address @t{0x1234}, and so on up to the size of the machine's
 physical memory.
 


@@ -616,13 +616,17 @@ Runs the executable whose name is given in @var{cmd_line}, passing any
 given arguments, and returns the new process's program id (pid).  Must
 return pid -1, which otherwise should not be a valid pid, if
 the program cannot load or run for any reason.
 given arguments, and returns the new process's program id (pid).  Must
 return pid -1, which otherwise should not be a valid pid, if
 the program cannot load or run for any reason.

+Thus, the parent process cannot return from the @code{exec} until it
+knows whether the child process successfully loaded its executable.
+You must use appropriate synchronization to ensure this.

 @end deftypefn
 
 @deftypefn {System Call} int wait (pid_t @var{pid})
 @end deftypefn
 
 @deftypefn {System Call} int wait (pid_t @var{pid})

-Waits for process @var{pid} to die and returns the status it passed to
-@code{exit}.  Returns -1 if @var{pid}
+If process @var{pid} is still alive, waits until it dies.
+Then, returns the status that @var{pid} passed to @code{exit},
+or -1 if @var{pid}

 was terminated by the kernel (e.g.@: killed due to an exception).  If
 was terminated by the kernel (e.g.@: killed due to an exception).  If

-@var{pid} is does not refer to a child of the
+@var{pid} does not refer to a child of the

 calling thread, or if @code{wait} has already been successfully
 called for the given @var{pid}, returns -1 immediately, without
 waiting.
 calling thread, or if @code{wait} has already been successfully
 called for the given @var{pid}, returns -1 immediately, without
 waiting.


@@ -654,11 +658,15 @@ of the rest.
 @deftypefn {System Call} bool create (const char *@var{file}, unsigned @var{initial_size})
 Creates a new file called @var{file} initially @var{initial_size} bytes
 in size.  Returns true if successful, false otherwise.
 @deftypefn {System Call} bool create (const char *@var{file}, unsigned @var{initial_size})
 Creates a new file called @var{file} initially @var{initial_size} bytes
 in size.  Returns true if successful, false otherwise.

+Opening the new file is a separate operation using the @code{open}
+system call.

 @end deftypefn
 
 @deftypefn {System Call} bool remove (const char *@var{file})
 Deletes the file called @var{file}.  Returns true if successful, false
 otherwise.
 @end deftypefn
 
 @deftypefn {System Call} bool remove (const char *@var{file})
 Deletes the file called @var{file}.  Returns true if successful, false
 otherwise.

+A file may be removed regardless of whether it is open or closed
+(@pxref{Removing an Open File}, for more information).

 @end deftypefn
 
 @deftypefn {System Call} int open (const char *@var{file})
 @end deftypefn
 
 @deftypefn {System Call} int open (const char *@var{file})


@@ -674,6 +682,12 @@ as explicitly described below.
 
 Each process has an independent set of file descriptors.  File
 descriptors are not inherited by child processes.
 
 Each process has an independent set of file descriptors.  File
 descriptors are not inherited by child processes.

+
+When a single file is opened more than once, whether by a single
+process or different processes, each @code{open} returns a new file
+descriptor.  Different file descriptors for a single file are closed
+independently in separate calls to @code{close} and they do not share
+a file position.

 @end deftypefn
 
 @deftypefn {System Call} int filesize (int @var{fd})
 @end deftypefn
 
 @deftypefn {System Call} int filesize (int @var{fd})


@@ -964,6 +978,18 @@ or the machine shuts down.
 You may modify the stack setup code to allocate more than one page of
 stack space for each process.  In the next project, you will implement a
 better solution.
 You may modify the stack setup code to allocate more than one page of
 stack space for each process.  In the next project, you will implement a
 better solution.

+
+@item What should happen if an @code{exec} fails midway through loading?
+
+@code{exec} should return -1 if the child process fails to load for
+any reason.  This includes the case where the load fails part of the
+way through the process (e.g.@: where it runs out of memory in the
+@code{multi-oom} test).  Therefore, the parent process cannot return
+from the @code{exec} system call until it is established whether the
+load was successful or not.  The child must communicate this
+information to its parent using appropriate synchronization, such as a
+semaphore (@pxref{Semaphores}), to ensure that the information is
+communicated without race conditions.

 @end table
 
 @node 80x86 Calling Convention
 @end table
 
 @node 80x86 Calling Convention