Index: userprog.texi =================================================================== RCS file: /home/courses/cs3204/gback/cvs/pintos/doc/userprog.texi,v retrieving revision 1.5 diff -u -r1.5 userprog.texi --- userprog.texi 8 Jan 2007 17:31:43 -0000 1.5 +++ userprog.texi 19 Nov 2007 14:42:53 -0000 @@ -616,13 +616,17 @@ 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}) -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 -@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. @@ -654,11 +658,16 @@ @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}) @@ -696,13 +705,13 @@ @deftypefn {System Call} int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size}) Writes @var{size} bytes from @var{buffer} to the open file @var{fd}. -Returns the number of bytes actually written, or -1 if the file could -not be written. +Returns the number of bytes actually written, which may be less than +@var{size} if some bytes could not be written. Writing past end-of-file would normally extend the file, but file growth is not implemented by the basic file system. The expected behavior is to write as many bytes as possible up to end-of-file and return the -actual number written, or -1 if no bytes could be written at all. +actual number written, or 0 if no bytes could be written at all. Fd 1 writes to the console. Your code to write to the console should write all of @var{buffer} in one call to @func{putbuf}, at least as @@ -970,6 +979,18 @@ 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