ref: d087174ead3f249a02a2ec437a49b122f096783c
dir: /fqa2.ms/
.\" This troff source is processed to create all forms of the
.\" 9FRONT DASH 1 book and the http://fqa.9front.org website.
.\" NOTE: Purely experimental. Methods employed may change.
.\" troff -ms -mpictures fqa2.ms | page
.\" htmlroff -u -ms -mhtml fqa2.ms >fqa2.html
.de FG \" .FG <basename>
.ie h .html - <img src="\\$1.\\$2" />
.el .BP \\$1.ps
.br
..
.po 1i \" page offset (from left)
.fp 1 R LucidaSans
.fp 2 I LucidaSansI
.fp 3 B LucidaSansB
.fp 4 BI LucidaSansI
.fp 5 CW LucidaCW
.paragraph 0
.margin 0
.HTML "FQA 2 - Getting To Know 9front
.html - <style type="text/css">body{font-size:10pt}; a{font-size:10pt}</style>
.html - <a href="fqa.html">FQA INDEX</a> |
.html - <a href="fqa1.html">FQA 1 - Introduction To 9front</a> |
.html - <a href="fqa3.html">FQA 3 - Hardware</a>
.html - <hr />
.SH
.LG
.ihtml h1 <h1>
FQA 2 - Getting To Know 9front
.ihtml h1
.NL
.R
.html - <a href="fqa2.html">html</a> |
.html - <a href="fqa2.pdf">pdf</a> |
.html - <a href="fqa2.ms">troff</a>
.FG voightkampff jpg
.html - <a name="2.1" />
.ihtml h2 <h2>
.SH
2.1 - Web Pages
.R
.ihtml h2
The official websites for the 9front project are located at:
•
.ihtml a <a href="http://9front.org">
http://9front.org
.ihtml a
\(em main website
•
.ihtml a <a href="http://docs.9front.org">
http://docs.9front.org
.ihtml a
\(em unofficial documentation, community maintained
•
.ihtml a <a href="http://fqa.9front.org">
http://fqa.9front.org
.ihtml a
\(em official documentation, ostensibly fictional
•
.ihtml a <a href="http://lists.9front.org">
http://lists.9front.org
.ihtml a
\(em mailing lists
•
.ihtml a <a href="http://man.9front.org">
http://man.9front.org
.ihtml a
\(em man pages
Somewhat outdated, and not entirely applicable to 9front is the Bell Labs Plan 9 wiki:
.ihtml a <a href="https://9p.io/wiki/plan9/plan_9_wiki/">
https://9p.io/wiki/plan9/plan_9_wiki/
.ihtml a
Some users have set up their own sites and pages with 9front specific information. As always, do not blindly enter commands you do not understand into your computer.
That said, much valuable information can be found at
.ihtml a <a href="http://cat-v.org">
http://cat-v.org
.ihtml a
regarding various aspects of UNIX, Plan 9, and software in general.
.html - <a name="2.2" />
.ihtml h2 <h2>
.SH
2.2 - Mailing Lists
.R
.ihtml h2
The 9front project maintains several mailing lists which users should subscribe to and follow. To subscribe to a mailing list, send an e-mail message to \fIlist\[email protected], where \fIlist\fR is the name of the mailing list. That address is an automated subscription service. In the body of your message, on a single line, you should include the subscribe command. For example:
.P1
subscribe
.P2
After subscribing, list messages are received from and sent to \fIlist\[email protected], where \fIlist\fR is the name of the mailing list.
The \fIlists\fR are as follows:
.ihtml ul <ul>
.IP
9front \(em general discussion
9front-commits \(em read-only log of commits to the
.ihtml a <a href="http://code.9front.org/plan9front">
9front mercurial repository
.ihtml a
9front-fqa \(em log of commits to, and discussion about
.ihtml a <a href="http://fqa.9front.org">
.CW http://fqa.9front.org
.ihtml a
9front-sysinfo \(em read-only log of
.ihtml a <a href="http://man.9front.org/1/sysinfo">
.CW sysinfo(1)
.ihtml a
output from user systems
.LP
.ihtml ul
To unsubscribe from a list, you will again send an e-mail message to \fIlist\[email protected]. It should look like this:
.P1
unsubscribe
.P2
Before posting a question on the 9front mailing list, please check the rest of this FQA. If asking a question possibly related to hardware, always include the output of
.ihtml a <a href="http://man.9front.org/1/sysinfo">
.CW sysinfo(1) !
.ihtml a
.bp
.html - <a name="2.2.1" />
.ihtml h3 <h3>
.SH
2.2.1 - Mailing List Archives
.R
.ihtml h3
Mailing list archives are available via 9p:
.P1
% 9fs 9front
post...
% ls /n/lists
/n/lists/9atom
/n/lists/9changes
/n/lists/9fans
/n/lists/9front
/n/lists/9front-commits
/n/lists/9front-fqa
/n/lists/9front-sysinfo
/n/lists/acme-sac
/n/lists/cat-v
/n/lists/cypherpunks
/n/lists/dlr
/n/lists/harvey
/n/lists/harvey-commits
/n/lists/harvey-issues
/n/lists/inferno
/n/lists/nix
/n/lists/plan9port-dev
/n/lists/sam-fans
/n/lists/sierra31
/n/lists/skunk-works
/n/lists/tscm-l
/n/lists/tuhs
/n/lists/werc
/n/lists/www-html
/n/lists/www-talk
/n/lists/www-vrml
.P2
Each of these directories contains messages sent to the respective mailing list in
.ihtml a <a href="http://plan9.stanleylieber.com/_books/nupas.pdf">
mdir
.ihtml a
format, one message per file. Erik Quanstrom's
.ihtml a <a href="http://plan9.stanleylieber.com/src/nupas.tgz">
nupas
.ihtml a
upas/fs (now merged with 9front upas) can mount these directories as mailboxes, for reading directly with a mail client.
.B Note:
Opening large mailboxes over a slow 9p link will be very slow.
.html - <a name="2.2.2" />
.ihtml h3 <h3>
.SH
2.2.2 - Other useful mailing lists
.R
.ihtml h3
.html - <br />
.FG 9fans jpg
.ihtml ul <ul>
.IP
.ihtml a <a href="https://9fans.topicbox.com/groups/9fans">
9fans
.ihtml a
\(em Official mailing list of Plan 9 from Bell Labs.
.LP
.ihtml ul
.html - <a name="2.3" />
.ihtml h2 <h2>
.SH
2.3 - Manual Pages
.R
.ihtml h2
9front comes with extensive documentation in the form of manual pages. Considerable effort is made to make sure the man pages are up-to-date and accurate. In all cases, 1.) the source, followed by 2.) the man pages, are considered the authoritative source of information for 9front.
You can find all the 9front man pages on the web at the following sites:
.ihtml ul <ul>
.IP
.ihtml a <a href="http://man.9front.org">
http://man.9front.org
.ihtml a
.ihtml a <a href="http://felloff.net/sys/man">
http://felloff.net/sys/man
.ihtml a
.ihtml a <a href="http://man.aiju.de">
http://man.aiju.de
.ihtml a
.ihtml a <a href="http://man.cat-v.org/9front">
http://man.cat-v.org/9front
.ihtml a
.ihtml a <a href="http://plan9.stanleylieber.com/man">
http://plan9.stanleylieber.com/man
.ihtml a
.LP
.ihtml ul
as well as on your 9front computer.
In general, if you know the name of a command or a manual page, you can read it by executing
.CW
man command\fR.
.R
For example:
.CW
man vi
.R
to read about the
.ihtml a <a href="http://man.9front.org/1/vi">
MIPS binary emulator.
.ihtml a
If you don't know the name of the command, or if
.CW
man command
.R
doesn't find the manual page, you can search the manual page database by executing
.CW
lookman something,
.R
where
.CW something
is a likely word that might appear in the title of the manual page you're looking for. For example:
.P1
% lookman vesa
man 3 vga # vga(3)
man 8 realemu # realemu(8)
man 8 vga # vga(8)
.P2
The resulting list is presented in the form of commands that can be highlighted and sent using rio's mouse button 2 menu.
For many, having a hardcopy of the man page can be useful. To make a printable copy of a man page:
.P1
man -t vga realemu | lp -dstdout > vga.ps
.P2
or:
.P1
man -t vga realemu | lp -dstdout | ps2pdf > vga.pdf
.P2
.html - <a name="2.3.1" />
.ihtml h3 <h3>
.SH
2.3.1 - How do I display a man page source file?
.R
.ihtml h3
The command
.CW
man -w
.R
prints the location of the man page's source file:
.P1
% man -w vga realemu
/sys/man/3/vga
/sys/man/8/realemu
/sys/man/8/vga
.P2
.html - <a name="2.3.2" />
.ihtml h3 <h3>
.SH
2.3.2 - How do I write my own manual page?
.R
.ihtml h3
As was mentioned in
.ihtml a <a href="fqa0.html#0.3.2">
.I
FQA 0.3.2 - Man pages,
.R
.ihtml a
Plan 9 man pages are divided into sections based upon the features they describe. For example, the troff source of the
.ihtml a <a href="http://man.9front.org/1/io">
.CW io(1)
.ihtml a
man page is located in section 1, in the file
.ihtml a <a href="http://code.9front.org/hg/plan9front/file/9d875116b400/sys/man/1/io">
.CW /sys/man/1/io .
.ihtml a
You can examine this troff source for a simple example of how to format and construct a typical man page.
For additional information, read:
.ihtml a <a href="http://doc.cat-v.org/plan_9/misc/man_page_writing_howto">
.I
How to Write a Plan 9 Manual Page,
.R
.ihtml a,
.ihtml a <a href="http://man.9front.org/6/man">
.CW man(6) ,
.ihtml a
.ihtml a <a href="http://man.9front.org/1/troff">
.CW troff(1)
.ihtml a
.bp
.html - <a name="2.4" />
.ihtml h2 <h2>
.SH
2.4 - Reporting Bugs
.R
.ihtml h2
.FG carson png
.I
"I have with Plan 9 Is there a way to"
.R
.B
Remember: 9front developers cannot read your mind.
.R
Very detailed information is required to diagnose most serious bugs.
.B
Also remember: It is possible you simply don't know what you're doing.
.R
If you do not understand how something is done in 9front or how it works, and can't figure out how to resolve the problem using the
.ihtml a <a href="fqa2.html#2.3">
manual pages,
.ihtml a
.ihtml a <a href="fqa8.html">
.I
FQA 8 - Using 9front,
.R
.ihtml a
or
.ihtml a <a href="fqa9.html">
.I
FQA 9 - Troubleshooting,
.R
.ihtml a
join
.CW
#9front
.R
on
.CW
irc.freenode.net
.R
or use the
.ihtml a <a href="fqa2.html#2.2">
mailing list ([email protected])
.ihtml a
to request help.
On the other hand, it's possible you really found a bug. If so, please file a bug report by sending an e-mail to
.ihtml a <a href="mailto:[email protected]">
.CW
[email protected].
.R
.ihtml a
.html - <a name="2.4.1" />
.ihtml h3 <h3>
.SH
2.4.1 - Your bug report SUCKS
.R
.ihtml h3
A minimum useful bug report contains the following:
.ihtml ul <ul>
.IP
• A complete description of what you did.
• A complete description of what you expected to happen.
• A complete description of what happened, instead.
.LP
.ihtml ul
Extra credit:
.ihtml ul <ul>
.IP
• The make and model of your computer.
• The URL returned when you run sysinfo -p on the affected system.
.LP
.ihtml ul
.html - <a name="2.4.2" />
.ihtml h3 <h3>
.SH
2.4.2 - How do I get more useful info for developers?
.R
.ihtml h3
The following sub-sections offer some useful tips.
.html - <a name="2.4.2.1" />
.ihtml h4 <h4>
.SH
2.4.2.1 - Take a photo of the panic screen
.R
.ihtml h4
Under some circumstances, you may not be able to recover text directly from a crashed system. In this situation, snap a photo of the screen, including as much of the screen in good focus as possible, and upload the image somewhere where it can be retrieved by developers.
.FG crash jpg
.bp
.html - <a name="2.4.2.2" />
.ihtml h4 <h4>
.SH
2.4.2.2 - Make a stack trace of a crashed process
.R
.ihtml h4
.P1
% hget http://www.jwz.org/blog/feed | rssread
panic: D2B called on non-block c580 (double-free?)
rssread 882285: suicide: sys: trap: fault read addr=0x0 pc=0x000038ef
% acid 882285
/proc/882285/text:386 plan 9 executable
/sys/lib/acid/port
/sys/lib/acid/386
acid: lstk()
abort()+0x0 /sys/src/libc/9sys/abort.c:6
ppanic(p=0xb5a0,fmt=0xbf72)+0x146 /sys/src/libc/port/malloc.c:166
pv=0xc100
msg=0xc310
v=0xdfffee90
n=0x2b
D2B(p=0xb5a0,v=0xc580)+0x5a /sys/src/libc/port/pool.c:966
a=0xc578
poolfreel(v=0xc580,p=0xb5a0)+0x20 /sys/src/libc/port/pool.c:1190
ab=0xc100
poolfree(p=0xb5a0,v=0xc580)+0x41 /sys/src/libc/port/pool.c:1325
free(v=0xc588)+0x23 /sys/src/libc/port/malloc.c:250
nextxmlpull(x=0xc548)+0x334 /usr/sl/src/xmlpull/xmlpull.c:221
nextxmlpull(x=0xc548)+0x2cb /usr/sl/src/xmlpull/xmlpull.c:316
main()+0x34 /usr/sl/src/rssread/rssread.c:159
st=0x1
f=0xc5a8
r=0x0
x=0xc548
_main+0x31 /sys/src/libc/386/main9.s:16
acid:
.P2
.html - <a name="2.4.2.3" />
.ihtml h4 <h4>
.SH
2.4.2.3 - Make a process snapshot
.R
.ihtml h4
To collect even more information than a stacktrace, you can also make a full process
snapshot, which includes all the memory of the program. The snapshot file
can later be analyzed (even on a different machine [even on a
different machine of a different architecture]).
.P1
% snap 882285 > rssread.snap
.P2
.ihtml a
.html - <a name="2.5" />
.ihtml h2 <h2>
.SH
2.5 - Sending Fixes
.R
.ihtml h2
We take fixes.
.html - <a name="2.5.1" />
.ihtml h3 <h3>
.SH
2.5.1 - How do I write good patches?
.R
.ihtml h3
Explain the problem that your change solves.
Explain why your change solves the problem well.
If applicable, explain how you tested the patch, and
give us a way of reproducing the issue.
.LP
Before Before making the patch, make sure your system is up to
date.
.LP
Make your code match the rest of the system. Look at
.ihtml a <a href="http://man.9front.org/6/style">
.CW style (6)
.ihtml a
for a summary of our code style.
.LP
If your patch includes new features or flags, be sure to update
the documentation.
.LP
If the patch is intrusive or significantly changes the design of
aspects of the system, it may be worth discussing it first.
Email works for this, but IRC works better.
.html - <a name="2.5.2" />
.ihtml h3 <h3>
.SH
2.5.2 - How do I send in my patches?
.R
.ihtml h3
To send changes, email [email protected] with your patch attached inline.
Generate the patch using
.P1
% bind -ac /dist/plan9front /
% cd /sys/src/your/changed/code
% hg diff . > /tmp/mypatch.diff
.P2
and paste the change into your email client of choice.
.LP
This project is run by hobbyists.
It may take some time for people to respond.
If you don't hear anything for more than a week or so, send a ping.
.html - <hr />
.html - <a href="fqa.html">FQA INDEX</a> |
.html - <a href="fqa1.html">FQA 1 - Introduction To 9front</a> |
.html - <a href="fqa3.html">FQA 3 - Hardware</a>