X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fuserprog.texi;h=25b7a70b7c6679bae217742b8e5203060b29abf3;hb=064e19becdc8969ddb605223b340606706a33f86;hp=d96d02d62bb1ce6387749ae066ffc41d98f0cf11;hpb=70d2a5ceda00c09e6b3909b266e92baf2e19703d;p=pintos-anon

diff --git a/doc/userprog.texi b/doc/userprog.texi
index d96d02d..25b7a70 100644
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -248,10 +248,24 @@ requirements:
 @itemize @bullet
 @item
 The kernel should print out the program's name and exit status
-whenever a process exits, e.g.@: @code{shell: exit(-1)}.  The name
-printed should be the full name passed to @func{process_execute},
-except that it is acceptable to truncate it to 15 characters to allow
-for the limited space in @struct{thread}.
+whenever a process terminates, e.g.@: @code{shell: exit(-1)}, whether
+termination is due to a call to the @code{exit} system call or for
+another reason.  The name printed should be the full name passed to
+@func{process_execute}, except that it is acceptable to truncate it to
+15 characters to allow for the limited space in @struct{thread}.
+
+@itemize @minus
+@item
+Do not print a message when a kernel thread that is not a process
+terminates.
+
+@item
+Do not print messages about process termination for the @code{halt}
+system call.
+
+@item
+No message need be printed when a process that fails to load.
+@end itemize
 
 @item
 Aside from this, the kernel should print out no other messages that
@@ -341,10 +355,11 @@ a successful exit.  Other values may be used to indicate user-defined
 conditions (usually errors).
 
 @item SYS_exec
-@itemx pid_t exec (const char *@var{file})
-Run the executable in @var{file} and return the new process's program
-id (pid).  If there is an error loading this program, returns pid -1,
-which otherwise should not be a valid id number.
+@itemx pid_t exec (const char *@var{cmd_line})
+Runs the executable whose name is given in @var{cmd_line}, passing any
+given arguments, and returns the new process's program id (pid).  If
+there is an error loading this program, may return pid -1, which
+otherwise should not be a valid id number.
 
 @item SYS_join
 @itemx int join (pid_t @var{pid})
@@ -358,11 +373,12 @@ be disrupted).
 @item SYS_create
 @itemx bool create (const char *@var{file}, unsigned @var{initial_size})
 Create a new file called @var{file} initially @var{initial_size} bytes
-in size.  Returns -1 if failed, 0 if OK.
+in size.  Returns true if successful, false otherwise.
 
 @item SYS_remove
 @itemx bool remove (const char *@var{file})
-Delete the file called @var{file}.  Returns -1 if failed, 0 if OK.
+Delete the file called @var{file}.  Returns true if successful, false
+otherwise.
 
 @item SYS_open
 @itemx int open (const char *@var{file})
@@ -383,8 +399,9 @@ Returns the size, in bytes, of the file open as @var{fd}.
 @item SYS_read
 @itemx int read (int @var{fd}, void *@var{buffer}, unsigned @var{size})
 Read @var{size} bytes from the file open as @var{fd} into
-@var{buffer}.  Returns the number of bytes actually read, or -1 if the
-file could not be read.  Fd 0 reads from the keyboard using
+@var{buffer}.  Returns the number of bytes actually read (0 at end of
+file), or -1 if the file could not be read (due to a condition other
+than end of file).  Fd 0 reads from the keyboard using
 @func{kbd_getc}.
 
 @item SYS_write
@@ -399,6 +416,14 @@ Changes the next byte to be read or written in open file @var{fd} to
 @var{position}, expressed in bytes from the beginning of the file.
 (Thus, a @var{position} of 0 is the file's start.)
 
+A seek past the current end of a file is not an error.  A later read
+obtains 0 bytes, indicating end of file.  A later write extends the
+file, filling any unwritten gap with zeros.  (However, in Pintos files
+have a fixed length until project 4 is complete, so writes past end of
+file will return an error.)  These semantics are implemented in the
+file system and do not require any special effort in system call
+implementation.
+
 @item SYS_tell
 @itemx unsigned tell (int @var{fd})
 Returns the position of the next byte to be read or written in open
@@ -495,7 +520,8 @@ isn't properly set up yet, this causes a page fault.
 @samp{system call!}.}
 
 Every reasonable program tries to make at least one system call
-(@func{exit}) and most programs make more than that.  The default
+(@func{exit}) and most programs make more than that.  Notably,
+@func{printf} invokes the @code{write} system call.  The default
 system call handler just prints @samp{system call!} and terminates the
 program.  You'll have to implement 2-2 before you see anything more
 interesting.  Until then, you can use @func{hex_dump} to convince
@@ -806,7 +832,7 @@ After we push all of the strings onto the stack, we adjust the stack
 pointer so that it is word-aligned: that is, we move it down to the
 next 4-byte boundary.  This is required because we will next be
 placing several words of data on the stack, and they must be aligned
-in order to be read correctly.  In our example, as you'll see below,
+to be read correctly.  In our example, as you'll see below,
 the strings start at address @t{0xffed}.  One word below that would be
 at @t{0xffe9}, so we could in theory put the next word on the stack
 there.  However, since the stack pointer should always be