aboutsummaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorPetter Rodhelind <petter.rodhelind@gmail.com>2021-02-18 20:21:24 +0100
committerPetter Rodhelind <petter.rodhelind@gmail.com>2021-02-18 20:21:24 +0100
commit181d56ee64da53279bb6ecf49c24ab54cfb7193f (patch)
treefc6c8736bb97790a257c5514998c583ffce7c41c /man
parent94c521bf102a74aec7e1a5c3a9ef5eaa968d4e14 (diff)
parent90971376a5e8620fc62579aa1b3be26245ec8c06 (diff)
downloadplan9port-master.tar.gz
plan9port-master.tar.bz2
plan9port-master.zip
Merge remote-tracking branch 'upstream/master'HEADmaster
Diffstat (limited to 'man')
-rw-r--r--man/man1/9c.116
-rw-r--r--man/man3/thread.366
-rw-r--r--man/man9/0intro.9p18
-rw-r--r--man/man9/attach.9p4
-rw-r--r--man/man9/clunk.9p2
-rw-r--r--man/man9/flush.9p4
-rw-r--r--man/man9/open.9p4
-rw-r--r--man/man9/openfd.9p8
-rw-r--r--man/man9/read.9p2
-rw-r--r--man/man9/remove.9p2
-rw-r--r--man/man9/stat.9p4
-rw-r--r--man/man9/version.9p2
-rw-r--r--man/man9/walk.9p4
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: