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

diff --git a/doc/userprog.texi b/doc/userprog.texi
index d96d02d..525e8ce 100644
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -248,10 +248,11 @@ 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}.
 
 @item
 Aside from this, the kernel should print out no other messages that
@@ -341,10 +342,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, returns pid -1, which
+otherwise should not be a valid id number.
 
 @item SYS_join
 @itemx int join (pid_t @var{pid})
@@ -358,11 +360,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 +386,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 +403,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