Rename the following reference documents to match their programs:
shell -> sh
viref -> vi
and rename the following to match their topic better:
ipctut -> sockets
ipc -> sockets-advanced
Also, the old "timed" and "timedop" docs are now ref5/timed and
ref8/timed respectively, as the first of these documented the
protocol.
Move all the reference manuals to subdirs of /usr/share/doc/reference.
We have subdirs ref1-ref9, corresponding to man page sections 1-9.
Everything that's the reference manual for a program (sections 1, 6,
8), C interface (sections 2, 3), driver or file system (section 4),
format or configuration (section 5), or kernel internal interface
(section 9) belongs in here.
Section 7 is a little less clear: some things that might go in section
7 if they were a man page aren't really reference manuals. So I'm only
putting things in reference section 7 that are (to me) clearly
reference material, rather than e.g. tutorials, guides, FAQs, etc.
This obviously leaves some room for debate, especially without first
editing the docs with this distinction in mind, but if people hate
what I've done things can always be moved again.
Note also that while roff macro man pages traditionally go in section
7, I have put all the roff documentation (macros, tools, etc.) in one
place in reference/ref1/roff. This will make it easier to find and
also easier to edit it into some kind of coherent form.
Update the <bsd.doc.mk> infrastructure, and update the docs to match
the new infrastructure.
- Build and install text, ps, pdf, and/or html, not roff sources.
- Don't wire the chapter numbers into the build system, or use them in
the installed pathnames. This didn't matter much when the docs were a
museum, but now that we're theoretically going to start maintaining
them again, we're going to add and remove documents periodically and
having the chapter numbers baked in creates a lot of thrashing for no
purpose.
- Specify the document name explicitly, rather than implicitly in a
path. Use this name (instead of other random strings) as the name
of the installed files.
- Specify the document section, which is the subdirectory of
/usr/share/doc to install into.
- Allow multiple subdocuments. (That is, multiple documents in one
output directory.)
- Enumerate the .png files groff emits along with html so they can be
installed.
- Remove assorted hand-rolled rules for running roff and roff widgetry
and add enough variable settings to make these unnecessary. This
includes support for
- explicit use of soelim
- refer
- tbl
- pic
- eqn
- Forcibly apply at least minimal amounts of sanity to certain
autogenerated roff files.
- Don't exclude USD.doc, SMM.doc, and PSD.doc directories from the
build, as they now actually do stuff.
Note: currently we can't generate pdf. This turns out to be a
nontrivial problem with no immediate solution forthcoming. So for now,
as a workaround, install compressed .ps as the printable form.
Evaluation of commands goes completely haywire if a file containing
a break/continue/return command outside its "intended" scope is sourced
using a dot command inside its "intended" scope. The main symptom is
not exiting from the sourced file when supposed to, leading to evaluation
of commands that were not supposed to be evaluated. A secondary symptom
is that these extra commands are not evaluated correctly, as some of them
are skipped. Some examples are listed in the How-To-Repeat section.
According to the POSIX standard, this is how it should work:
dot:
The shell shall execute commands from the file in the current
environment.
break:
The break utility shall exit from the smallest enclosing for, while,
or until loop, [...]
continue:
The continue utility shall return to the top of the smallest
enclosing for, while, or until loop, [...]
return:
The return utility shall cause the shell to stop executing
the current function or dot script. If the shell is not currently
executing a function or dot script, the results are unspecified.
It is clear that return should return from a sourced file, which
it does not do. Whether break and continue should work from the sourced
file might be debatable. Because the dot command says "in the current
environment", I'd say yes. In any case, it should not fail in weird
ways like it does now!
The problems occur with return (a) and break/continue (b) because:
1) dotcmd() does not record the function nesting level prior to
sourcing the file nor does it touch the loopnest variable,
leading to either
2 a) returncmd() being unable to detect that it should not set
evalskip to SKIPFUNC but SKIPFILE, or
b) breakcmd() setting evalskip to SKIPCONT or SKIPBREAK,
leading to
3) cmdloop() not detecting that it should skip the rest of
the file, due to only checking for SKIPFILE.
The result is that cmdloop() keeps executing lines from the file
whilst evalskip is set, which is the main symptom. Because
evalskip is checked in multiple places in eval.c, the secondary
symptom appears.
>How-To-Repeat:
Run the following script:
printf "break\necho break1; echo break2" >break
printf "continue\necho continue1; echo continue2" >continue
printf "return\necho return1; echo return2" >return
while true; do . ./break; done
for i in 1 2; do . ./continue; done
func() {
. ./return
}
func
No output should be produced, but instead this is the result:
break1
continue1
continue1
return1
The main symptom is evident from the unexpected output and the secondary
one from the fact that there are no lines with '2' in them.
>Fix:
Here is patch to src/bin/sh to fix the above problems. It keeps
track of the function nesting level at the beginning of a dot command
to enable the return command to work properly.
I also changed the undefined-by-standard functionality of the return
command when it's not in a dot command or function from (indirectly)
exiting the shell to being silently ignored. This was done because
the previous way has at least one bug: the shell exits without asking
for confirmation when there are stopped jobs.
Because I read the standard to mean that break and continue should have
an effect outside the sourced file, that's how I implemented it. For what
it's worth, this also seems to be what bash does. Also laziness, because
this way required no changes to loopnesting tracking. If this is not
wanted, it might make sense to move the nesting tracking to the inputfile
stack.
The patch also does some clean-up to reduce the amount of global
variables by moving the dotcmd() and the find_dot_file() functions from
main.c to eval.c and making in_function() a proper function.
We have written a diff to our ls(1) to recover the traditional behaviour
of -f implying -a. This change does not only accommodates POSIX.1
but also matches traditional UNIX.
OpenBSD commit message:
CVSROOT: /cvs
Module name: src
Changes by: sobrado@cvs.openbsd.org 2014/03/31 14:54:37
Modified files:
bin/ls : ls.1 ls.c
Log message:
restore the traditional behavior of -f implying -a; apparently Keith Bostic
forgot to restore it when the -f flag was put back on 2nd of September 1989,
after being removed on 16th of August as a consequence of issues getting it
working over NFS, so deviation from traditional UNIX behavior in all BSDs
looks like an historical accident; as a side effect, this change accommodates
behavior of this option to IEEE Std 1003.1-2008 (``POSIX.1'').
joint work with jmc@ (who found the inaccuracy in our implementation),
schwarze@ (who provided a detailed tracking of historical facts) and millert@
ok millert@, schwarze@
The -H, -L and -P options are ignored unless the -R option is
specified. In addition, these options override each other and the
command's actions are determined by the last one specified.
Add:
The default is as if the -P option had been specified.
bin/cat/cat.c 976654 Argument cannot be negative
(missing check for fileno result, stdout)
bin/cat/cat.c 976653 Improper use of negative value
(missing check for fileno result, stdin)
sh +nounset and `for X; do` iteration fails if parameter set empty
by applying and testing FreeBSD's patch of Oct 24 2009 for this; see
http://svnweb.freebsd.org/base/head/bin/sh/expand.c?r1=198453&r2=198454
Also created an ATF test in tests/bin/sh/t_expand.sh for this error and
corrected a space->tabs problem there as well.
XXX: someone should fix all the .Ev stuff because some of them are just
shell variables .Va and are not really exported to the environment. See
the FreeBSD man page.
-A Display the FQDN of each address on all interfaces.
-a Display alias name(s) of the host.
-d Display the DNS domain.
-f Display the FQDN for the hostname.
-I Display each IP address on all interfaces.
-i Display the IP address(es) for the hostname.
this fix was taken from FreeBSD SVN rev 199953 (Jilles Tjoelker)
------------------------------------------------------------------------
r199953 | jilles | 2009-11-30 07:33:59 +0900 (Mon, 30 Nov 2009) | 16 lines
Fix some cases where file descriptors from redirections leak to programs.
- Redirecting fds that were not open before kept two copies of the
redirected file.
sh -c '{ :; } 7>/dev/null; fstat -p $$; true'
(both fd 7 and 10 remained open)
- File descriptors used to restore things after redirection were not
set close-on-exec, instead they were explicitly closed before executing
a program normally and before executing a shell procedure. The latter
must remain but the former is replaced by close-on-exec.
sh -c 'exec 7</; { exec fstat -p $$; } 7>/dev/null; true'
(fd 10 remained open)
The examples above are simpler than the testsuite because I do not want to
use fstat or procstat in the testsuite.
the TOOLDIR version of libnbcompat, associated include files,
and associated defs.mk file, instead of the version from the
.OBJDIR of src/tools/compat. This should fix PR 47188.
ls.1:
- Sort options in `SYNOPSIS', the option list, and texts within
the man page;
- improve wording;
- improve macro usage;
- use more consistency regarding (locations for) information about
which options override which;
- cross-reference `-d' and `-R';
- simplify description of `-k', removing redundant and unneeded
information;
- sort entry type list (but leave `-a' and `-A' as they are, given
their meaning);
- correct / augment description of `BLOCKSIZE' environment variable
in `ENVIRONMENT' section;
- bump date.
ls.c:
- Sort options in `usage';
- augment comment about when to figure out block size.
- improve (create more consistency in) spelling;
- remove unnecessary (and in part ignored) macros, as well as an
unnecessary argument to `.Bl' (fixes mandoc(1) warnings);
- improve wording;
- bump date.
Patch from Bug Hunting.
erroneously think that negative time_t's never fit in 32 bits. Rework
conversion code to always use uintmax_t, and detect negative values.
XXX[1]: Perhaps we should do the same (use a signed conversion) for all
fields not just for time_t
XXX[2]: pullup for 6
- correct `SYNOPSIS';
- improve macro usage;
- mention argument name for `-f' (and change list width for it);
- correct misplacement of periods (`.') and a parenthese (`(');
- fix typo;
- bump date.
From Bug Hunting.
we opened is the one we expected to get. Also use O_NOFOLLOW to help
avoid even opening devices, which sometimes produce side effects.
Reported by Radoslaw A. Zarzynski.
depend on new devname_r(3) as heart. Add /dev/pts magic directly to
devname(3). While it can lead to returning non-existing paths, the
behavior is more consistent that way. Drop caching layer in devname(3),
it doesn't buy anything for the common case of having access to the
database. Teach devname(3) proper fallback behavior of scanning /dev.
Create both old-style and new-style database for now in /etc/rc.d/sysdb.
- bump the manpage's date (because of the next change);
- note that cp(1) does not preserve hard links (even with `-R'),
and refer to pax(1) there as well as in the `SEE ALSO' section
for such functionality (this change is based upon a similar note
in FreeBSD's version of the manpage);
- change a wording, for more overall consistency.
state of the stream. Change argument of the seek function to funopen() from
fpos_t to off_t. Make f{g,s}etpos() use the new fpos_t struct, while providing
backwards compatible entry points. Approved by releng@
char 160 in the input to csh, lead it to an infinite loop, because tcsh tables
counted this as a space character, but the word logic switch does not. Change
that character tables, so that this does not count as a spacing character
anymore, by syncing the table with the one from tcsh.
- error out when an unknown specifier is used. Do this in f_msgfmt(),
before dd(1) starts operation.
- allow buffer_write() to flush the internal buffer even when NULL is
passed as parameter.
Some whitespace fixes too.
output of the information summary returned by dd(1). This can be used
to specify messages in a more usable (or parseable) format like
human-readable values.
My intent is to re-use this for building image files and quick I/O
benchmarking.
Reviewed by tsutsui@ on tech-userlevel. See also
http://mail-index.netbsd.org/tech-userlevel/2010/12/03/msg004179.html
Some examples:
$ dd if=/dev/zero of=/dev/null bs=1m count=1 msgfmt=human
1+0 records in
1+0 records out
1048576 bytes (1,0 MB) transferred in 0.001 secs (1048576000 bytes/sec - 1,0 GB/sec)
$ dd if=/dev/zero of=/dev/null count=1 msgfmt='
> <speed>%E</speed>
> <time>%s</time>
> <bytes>%b</bytes>
> '
<speed>500 KB/sec</speed>
<time>0.001</time>
<bytes>512</bytes>
if the block has moved, arrange so that trailing newlines are never placed in the string
in the first place, by accumulating them and adding them only after we've encountered a
non-newline character. This allows also for more efficient appending since we know how much
we need beforehand. From FreeBSD.
it will always be displayed when an unprivilegied user moves files across
filesystems (mv(1) uses cp -p in that case). After all, there is no warning
that we loose a setuid bit during a move or copy, so this makes sense.
Fixes bin/45259
Also introduce library functions for copying extended attributes from one
file to another:
- extattr_copy_file, extattr_copy_fd, extattr_copy_link, with FreeBSD style,
where a namespace is to be supplied
- cpxattr, fcpxattr, lcpxattr, with Linux style, where all namespaces
accessible to the caller are copied, and the others are silently ignored.
dholland