Improve wording.

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index 88d8bbddccded5d36354ac30603901d01cc458e5..df25ed9ed474d0122ec52912fc0422c7c2155a44 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -616,13 +616,16 @@ 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.
+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})
 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} 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
@@ -655,11 +658,16 @@ 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.
+Creating a new file does not open it: opening the new file is a
+separate operation which would require a @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.
+A file may be removed regardless of whether it is open or closed, and
+removing an open file does not close it.  @xref{Removing an Open
+File}, for details.
 @end deftypefn
 
 @deftypefn {System Call} int open (const char *@var{file})
@@ -971,6 +979,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.
+
+@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