Clarify that create and remove work on files, not on file descriptors.

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index bb05dfb326b091e48cdeff21f744c73ddd0179f6..75bc8e542ffd3772fd58b10808f8527b3aadbe36 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.
 


@@ -314,11 +314,6 @@ the running process.  However, even in the kernel, an attempt to
 access memory at an unmapped user virtual address
 will cause a page fault.
 
 access memory at an unmapped user virtual address
 will cause a page fault.
 

-You must handle memory fragmentation gracefully, that is, a process that
-needs @var{N} pages of user virtual memory must not require those pages
-to be contiguous in physical memory (or, equivalently, in kernel virtual
-memory).
-

 @menu
 * Typical Memory Layout::       
 @end menu
 @menu
 * Typical Memory Layout::       
 @end menu


@@ -624,10 +619,11 @@ the program cannot load or run for any reason.
 @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.


@@ -659,11 +655,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})


@@ -679,6 +679,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})