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 65caf334a8495cdc3a61de1fe945b85adfa67117..75bc8e542ffd3772fd58b10808f8527b3aadbe36 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -20,9 +20,7 @@ assignment.  The ``alarm clock'' functionality may be useful in
 projects 3 and 4, but it is not strictly required.
 
 You might find it useful to go back and reread how to run the tests
 projects 3 and 4, but it is not strictly required.
 
 You might find it useful to go back and reread how to run the tests

-(@pxref{Testing}).  In particular, the tests for project 2 (and later
-projects) will run much faster if you use the qemu emulator, e.g.@:
-via @code{make check PINTOSOPTS='--qemu'}.
+(@pxref{Testing}).

 
 @menu
 * Project 2 Background::        
 
 @menu
 * Project 2 Background::        


@@ -303,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.
 


@@ -316,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


@@ -573,13 +566,13 @@ word is the program name, the second word is the first argument, and so
 on.  That is, @code{process_execute("grep foo bar")} should run
 @command{grep} passing two arguments @code{foo} and @code{bar}.
 
 on.  That is, @code{process_execute("grep foo bar")} should run
 @command{grep} passing two arguments @code{foo} and @code{bar}.
 

-Within a command line, multiple spaces are equivalent to a single space,
-so that @code{process_execute("grep foo bar")} is equivalent to our
-original example.  You can impose a reasonable limit on the length of
-the command line arguments.  For example, you could limit the arguments
-to those that will fit in a single page (4 kB).  (There is an unrelated
-limit of 128 bytes on command-line arguments that the @command{pintos}
-utility can pass to the kernel.)
+Within a command line, multiple spaces are equivalent to a single
+space, so that @code{process_execute("grep @w{ }foo @w{ }@w{ }bar")}
+is equivalent to our original example.  You can impose a reasonable
+limit on the length of the command line arguments.  For example, you
+could limit the arguments to those that will fit in a single page (4
+kB).  (There is an unrelated limit of 128 bytes on command-line
+arguments that the @command{pintos} utility can pass to the kernel.)

 
 You can parse argument strings any way you like.  If you're lost,
 look at @func{strtok_r}, prototyped in @file{lib/string.h} and
 
 You can parse argument strings any way you like.  If you're lost,
 look at @func{strtok_r}, prototyped in @file{lib/string.h} and


@@ -626,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.


@@ -661,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})


@@ -681,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})


@@ -692,8 +696,7 @@ Reads @var{size} bytes from the file open as @var{fd} into
 @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
 @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}.  (Keyboard input will not work if you pass the
-@option{-v} option to @command{pintos}.)
+@func{input_getc}.

 @end deftypefn
 
 @deftypefn {System Call} int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})
 @end deftypefn
 
 @deftypefn {System Call} int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})


@@ -912,12 +915,6 @@ You can choose whatever suitable types you like for @code{tid_t} and
 @code{pid_t}.  By default, they're both @code{int}.  You can make them
 a one-to-one mapping, so that the same values in both identify the
 same process, or you can use a more complex mapping.  It's up to you.
 @code{pid_t}.  By default, they're both @code{int}.  You can make them
 a one-to-one mapping, so that the same values in both identify the
 same process, or you can use a more complex mapping.  It's up to you.

-
-@item Keyboard input doesn't work.
-
-You are probably passing @option{-v} to @command{pintos}, but
-serial input isn't implemented.  Don't use @option{-v} if you
-want to use the shell or otherwise need keyboard input.

 @end table
 
 @menu
 @end table
 
 @menu