Merge remote-tracking branch 'upstream/master'HEADmaster

13 files changed, 63 insertions, 73 deletions

diff --git a/man/man1/9c.1 b/man/man1/9c.1
index dd15926d..943df6fb 100644
--- a/man/man1/9c.1
+++ b/man/man1/9c.1
@@ -1,6 +1,6 @@
 .TH 9C 1
 .SH NAME
-9c, 9a, 9l, 9ar \- C compiler, assembler, linker, archiver
+9c, 9l, 9ar \- C compiler, assembler, linker, archiver
 .SH SYNOPSIS
 .B 9c
 [
@@ -14,10 +14,6 @@
 .I file
 \&...
 .PP
-.B 9a
-.I file
-\&...
-.PP
 .B 9l
 [
 .I -o
@@ -81,12 +77,6 @@ also defines
 .B __sun__
 on SunOS systems.
 .PP
-.I 9a
-assembles the named files into object files for the current system.
-Unlike some system assemblers, it does
-.I not
-promise to run the C preprocessor on the source files.
-.PP
 .I 9l
 links the named object files and libraries to create the target executable.
 Each
@@ -203,10 +193,6 @@ rebuilt whenever the archive is modified.
 Compile three C source files.
 .TP
 .L
-9a file4.s
-Assemble one assembler source file.
-.TP
-.L
 9ar rvc lib.a file[12].o
 Archive the first two object files into a library.
 .TP
diff --git a/man/man3/thread.3 b/man/man3/thread.3
index 6c6b4602..c0a59091 100644
--- a/man/man3/thread.3
+++ b/man/man3/thread.3
@@ -33,6 +33,7 @@ threadintgrp,
 threadkill,
 threadkillgrp,
 threadmain,
+threadmaybackground,
 threadnotify,
 threadid,
 threadpid,
@@ -80,6 +81,7 @@ struct Alt {
 .ft L
 .ta \w'\fLChannel* 'u +4n +4n +4n +4n
 void	threadmain(int argc, char *argv[])
+int	threadmaybackground(void)
 int	mainstacksize
 int	proccreate(void (*fn)(void*), void *arg, uint stacksize)
 int	threadcreate(void (*fn)(void*), void *arg, uint stacksize)
@@ -156,27 +158,21 @@ by
 The thread library provides a
 .I main
 function that sets up a proc with a single thread executing
-.I threadmain
-on a stack of size
-.I mainstacksize
-(default eight kilobytes).
-To set
-.IR mainstacksize ,
-declare a global variable
-initialized to the desired value
-.RI ( e.g. ,
-.B int
-.B mainstacksize
-.B =
-.BR 1024 ).
-When using the
+.IR threadmain .
+.PP
+Every thread is backed by an operating system-provided
 .I pthread
-library, 
-.B mainstacksize
-is ignored, as is the stack size argument to
-.BR proccreate :
-the first thread in each proc
-runs on the native system stack.
+and runs on its system-provided stack;
+.I mainstacksize
+and the the stack size arguments to
+.I proccreate
+and
+.I threadcreate
+are ignored.
+Although each thread is backed by a separate
+.IR pthread ,
+the threads in a proc are still scheduled non-preemptively
+as on Plan 9 and as described below.
 .PP
 .I Threadcreate
 creates a new thread in the calling proc, returning a unique integer
@@ -185,7 +181,7 @@ executes
 .I fn(arg)
 on a stack of size
 .IR stacksize .
-Thread stacks are allocated in shared memory, making it valid to pass 
+Thread stacks are allocated in shared memory, making it valid to pass
 pointers to stack variables between threads and procs.
 .I Proccreate
 creates a new proc, and inside that proc creates
@@ -207,7 +203,7 @@ returning the id of the created thread.
 .\" in
 .\" .IR rforkflag .)
 .\" .I Proccreate
-.\" is identical to 
+.\" is identical to
 .\" .I procrfork
 .\" with
 .\" .I rforkflag
@@ -238,6 +234,14 @@ When the last thread in
 .IR threadmain 's
 proc exits, the program will appear to its parent to have exited.
 The remaining procs will still run together, but as a background program.
+This functionality can only be relied upon if the program defines a function
+.I threadmaybackground
+returning a non-zero result.
+Programs that do not define such a
+.I threadmaybackground
+will crash instead should the last thread in
+.IR threadmain 's
+proc exit leaving behind other running procs.
 .PP
 The threads in a proc are coroutines, scheduled nonpreemptively
 in a round-robin fashion.
@@ -341,18 +345,18 @@ Also for debugging,
 threads have a string state associated with them.
 .I Threadsetstate
 sets the state string.
-There is no 
+There is no
 .IR threadgetstate ;
 since the thread scheduler resets the state to
 .B Running
-every time it runs the thread, 
+every time it runs the thread,
 it is only useful for debuggers to inspect the state.
 .PP
 .I Threaddata
 returns a pointer to a per-thread pointer
 that may be modified by threaded programs for
 per-thread storage.
-Similarly, 
+Similarly,
 .I procdata
 returns a pointer to a per-proc pointer.
 .PP
@@ -398,11 +402,11 @@ response.
 .I Threadexecl
 and
 .I threadexec
-will duplicate 
+will duplicate
 (see
 .MR dup (3) )
 the three file descriptors in
-.I fd 
+.I fd
 onto standard input, output, and error for the external program
 and then close them in the calling thread.
 Beware of code that sets
@@ -467,9 +471,9 @@ operation blocks until the corresponding
 operation occurs and
 .IR "vice versa" .
 .IR Chancreate
-allocates a new channel 
+allocates a new channel
 for messages of size
-.I elsize 
+.I elsize
 and with a buffer holding
 .I nel
 messages.
@@ -645,7 +649,7 @@ from the main proc before any other procs have been created.
 To create new processes, use
 .IR proccreate .
 .\" .PP
-.\" It is safe to use 
+.\" It is safe to use
 .\" .IR rfork
 .\" (see
 .\" .IR fork (3))
@@ -663,7 +667,7 @@ To create new processes, use
 .\" .BR RFCENVG.
 .\" (To create new processes, use
 .\" .I proccreate
-.\" and 
+.\" and
 .\" .IR procrfork .)
 .\" As mentioned above,
 .\" the thread library depends on all procs being in the
diff --git a/man/man9/0intro.9p b/man/man9/0intro.9p
index f432cf51..30e153a1 100644
--- a/man/man9/0intro.9p
+++ b/man/man9/0intro.9p
@@ -21,7 +21,7 @@ such a machine is called, somewhat confusingly, a
 Another possibility for a server is to synthesize
 files on demand, perhaps based on information on data structures
 maintained in memory; the
-.IM plumber (4)
+.MR plumber (4)
 server is an example of such a server.
 .PP
 A
@@ -63,7 +63,7 @@ bytes of data.
 Text strings are represented this way,
 with the text itself stored as a UTF-8
 encoded sequence of Unicode characters (see
-.IM utf (7) ).
+.MR utf (7) ).
 Text strings in 9P messages are not
 .SM NUL\c
 -terminated:
@@ -114,7 +114,7 @@ Plan 9 names may contain any printable character (that is, any character
 outside hexadecimal 00-1F and 80-9F)
 except slash.)
 Messages are transported in byte form to allow for machine independence;
-.IM fcall (3)
+.MR fcall (3)
 describes routines that convert to and from this form into a machine-dependent
 C structure.
 .SH MESSAGES
@@ -348,7 +348,7 @@ a ``current file'' on the server.
 Fids are somewhat like file descriptors in a user process,
 but they are not restricted to files open for I/O:
 directories being examined, files being accessed by
-.IM stat (3)
+.MR stat (3)
 calls, and so on \(em all files being manipulated by the operating
 system \(em are identified by fids.
 Fids are chosen by the client.
@@ -461,7 +461,7 @@ to have their input or output attached to fids on 9P servers.
 See
 .IR openfd (9p)
 and
-.IM 9pclient (3)
+.MR 9pclient (3)
 for details.
 .PP
 The
@@ -475,7 +475,7 @@ access permissions (read, write and execute for owner, group and public),
 access and modification times, and
 owner and group identifications
 (see
-.IM stat (3) ).
+.MR stat (3) ).
 The owner and group identifications are textual names.
 The
 .B wstat
@@ -523,12 +523,12 @@ into 9P messages.
 .SS Unix
 On Unix, 9P services are posted as Unix domain sockets in a
 well-known directory (see
-.IM getns (3)
+.MR getns (3)
 and
-.IM 9pserve (4) ).
+.MR 9pserve (4) ).
 Clients connect to these servers using a 9P client library
 (see
-.IM 9pclient (3) ).
+.MR 9pclient (3) ).
 .SH DIRECTORIES
 Directories are created by
 .B create
diff --git a/man/man9/attach.9p b/man/man9/attach.9p
index 3a5104d5..4160f30d 100644
--- a/man/man9/attach.9p
+++ b/man/man9/attach.9p
@@ -122,7 +122,7 @@ and
 and
 .I fsauth
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generate
 .B attach
 and
@@ -163,6 +163,6 @@ transactions.
 .\" .B mount
 .\" system call on an uninitialized connection.
 .SH SEE ALSO
-.IM 9pclient (3) ,
+.MR 9pclient (3) ,
 .IR version (9P),
 Plan 9's \fIauthsrv\fR(6)
diff --git a/man/man9/clunk.9p b/man/man9/clunk.9p
index 3277c4b0..f014ac42 100644
--- a/man/man9/clunk.9p
+++ b/man/man9/clunk.9p
@@ -41,7 +41,7 @@ generated by
 and
 .I fsunmount
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 and indirectly by other actions such as failed
 .I fsopen
 calls.
diff --git a/man/man9/flush.9p b/man/man9/flush.9p
index d0987cac..862ab9a4 100644
--- a/man/man9/flush.9p
+++ b/man/man9/flush.9p
@@ -99,11 +99,11 @@ flushing a
 and flushing an invalid tag.
 .SH ENTRY POINTS
 The
-.IM 9pclient (3)
+.MR 9pclient (3)
 library does not generate
 .B flush
 transactions..
-.IM 9pserve (4)
+.MR 9pserve (4)
 generates
 .B flush
 transactions to cancel transactions pending when a client hangs up.
diff --git a/man/man9/open.9p b/man/man9/open.9p
index 1f74eb07..8a54f72c 100644
--- a/man/man9/open.9p
+++ b/man/man9/open.9p
@@ -160,7 +160,7 @@ in this case, the
 .I fscreate
 call
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 uses
 .B open
 with truncation.
@@ -209,7 +209,7 @@ again.
 and
 .I fscreate
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 both generate
 .B open
 messages; only
diff --git a/man/man9/openfd.9p b/man/man9/openfd.9p
index 56fb392a..620b1991 100644
--- a/man/man9/openfd.9p
+++ b/man/man9/openfd.9p
@@ -43,18 +43,18 @@ it cannot be
 .PP
 .I Openfd
 is implemented by
-.IM 9pserve (4) .
+.MR 9pserve (4) .
 9P servers that post their services using
-.IM 9pserve (4)
+.MR 9pserve (4)
 (or indirectly via
-.IM post9pservice (3) )
+.MR post9pservice (3) )
 will never see a
 .B Topenfd
 message.
 .SH ENTRY POINTS
 .I Fsopenfd
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generates an
 .B openfd
 message.
diff --git a/man/man9/read.9p b/man/man9/read.9p
index 515f85c3..675bb773 100644
--- a/man/man9/read.9p
+++ b/man/man9/read.9p
@@ -114,7 +114,7 @@ to be transferred atomically.
 and
 .I fswrite
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generate the corresponding messages.
 Because they take an offset parameter, the
 .I fspread
diff --git a/man/man9/remove.9p b/man/man9/remove.9p
index 79a646a1..232c88f6 100644
--- a/man/man9/remove.9p
+++ b/man/man9/remove.9p
@@ -45,7 +45,7 @@ so other fids typically remain usable.
 .SH ENTRY POINTS
 .I Fsremove
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generates
 .B remove
 messages.
diff --git a/man/man9/stat.9p b/man/man9/stat.9p
index b92f2d69..7706d3eb 100644
--- a/man/man9/stat.9p
+++ b/man/man9/stat.9p
@@ -88,7 +88,7 @@ The
 and
 .I convD2M
 routines (see
-.IM fcall (3) )
+.MR fcall (3) )
 convert between directory entries and a C structure called a
 .BR Dir .
 .PP
@@ -263,7 +263,7 @@ messages are generated by
 and
 .IR fsdirstat
 (see
-.IM 9pclient (3) ).
+.MR 9pclient (3) ).
 .PP
 .B Wstat
 messages are generated by
diff --git a/man/man9/version.9p b/man/man9/version.9p
index 99f30239..c71ee556 100644
--- a/man/man9/version.9p
+++ b/man/man9/version.9p
@@ -91,7 +91,7 @@ requests is called a
 .SH ENTRY POINTS
 .I Fsversion
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generates
 .B version
 messages;
diff --git a/man/man9/walk.9p b/man/man9/walk.9p
index b48b947b..735b7dcb 100644
--- a/man/man9/walk.9p
+++ b/man/man9/walk.9p
@@ -149,13 +149,13 @@ may be packed in a single message.
 This constant is called
 .B MAXWELEM
 in
-.IM fcall (3) .
+.MR fcall (3) .
 Despite this restriction, the system imposes no limit on the number of elements in a file name,
 only the number that may be transmitted in a single message.
 .SH ENTRY POINTS
 .I Fswalk
 (see
-.IM 9pclient (3) )
+.MR 9pclient (3) )
 generates walk messages.
 One or more walk messages may be generated by
 any call that evaluates file names: