1872 lines
66 KiB
HTML
1872 lines
66 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type"
|
|
content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 2.0">
|
|
<title>NAME</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>tee - Pipe fitting.</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>tee</b> [ -<b>ai</b> ] [ <i>file</i> ...]</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>The <b>tee</b> utility copies standard input to standard
|
|
output, making a copy in zero or more files. The output
|
|
is unbuffered.<p>The following options are available:</p>
|
|
<p>-<b>a</b> Append the output to the files rather than
|
|
overwriting them.</p>
|
|
<p>-<b>i</b> Ignore the <b>SIGINT</b> signal.</p>
|
|
<p>The following operands are available:</p>
|
|
<p><i>file</i> A pathname of an output file .</p>
|
|
<p>The <b>tee</b> utility takes the default action for
|
|
all signals, except in the event of the -<b>i</b> option.</p>
|
|
<p>The <b>tee</b> utility exits 0 on success, and >0
|
|
if an error occurs.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>STANDARDS</b></p>
|
|
|
|
<dir>
|
|
<li>The <b>tee</b> function is expected to be POSIX p1003.2
|
|
compatible.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><i>GNO/Shell User's Manual </i>, <b>signal</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>time - time a command</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>time</b> <i>command</i></li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>The <b>time</b> command lets the specified <b>command</b>
|
|
execute and then outputs the amount of elapsed real time,
|
|
the time spent in the operating system, and the time
|
|
spent in execution of the command. Times are reported in
|
|
seconds and are written to standard error.<p>The <b>time</b>
|
|
command can be used to cause a command to be timed no
|
|
matter how much </p>
|
|
<p>CPU time it takes. For example:</p>
|
|
<p><font face="Courier New">% /bin/time cp /etc/rc
|
|
/usr/bill/rc</font></p>
|
|
<p><font face="Courier New">0.1 real 0.0 user 0.0 sys</font></p>
|
|
<p><font face="Courier New">% /bin/time nroff sample1
|
|
> sample1.nroff</font></p>
|
|
<p><font face="Courier New">3.6 real 2.4 user 1.2 sys</font></p>
|
|
<p>This example indicates that the <b>cp</b> command used
|
|
negligible amounts of user ( <i>user</i> ) and system
|
|
time ( <i>sys</i> ), and had an elapsed time ( <i>real</i>
|
|
) of 1/10 second (0.1). The <b>nroff</b> command used 2.4
|
|
seconds of user time and 1.2 seconds of system time, and
|
|
required 3.6 seconds of elapsed time.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RESTRICTIONS</b></p>
|
|
|
|
<dir>
|
|
<li>Times are measured to an accuracy of 1/60 second. Thus,
|
|
the sum of the user and system times can be larger than
|
|
the elapsed time, but this isn't likely.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>tr - translate characters</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>tr</b> [ -<b>cds</b> ] [ <i>string1</i> [ <i>string2</i>
|
|
] ]</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>tr</b> copies the standard input to the standard
|
|
output with substitution or deletion of selected
|
|
characters. The arguments <i>string1</i> and <i>string2</i>
|
|
are considered sets of characters. Any input character
|
|
found in <i>string1</i> is mapped into the character in
|
|
the corresponding position within <i>string2</i>. When <i>string2</i>
|
|
is short, it is padded to the length of <i>string1</i> by
|
|
duplicating its last character.<p>In either string the
|
|
notation '<b>a - b' </b>denotes a range of characters
|
|
from <b>a</b> to <b>b</b> in increasing ASCII order. The
|
|
character \, followed by 1, 2 or 3 octal digits stands
|
|
for the character whose ASCII code is given by those
|
|
digits. As with the shell, the escape character \,
|
|
followed by any other character, escapes any special
|
|
meaning for that character.</p>
|
|
<p>When <i>string2</i> is short, characters in <i>string1</i>
|
|
with no corresponding character in <i>string2</i> are not
|
|
translated.</p>
|
|
<p>In either string the following abbreviation
|
|
conventions introduce ranges of characters or repeated
|
|
characters into the strings.</p>
|
|
<p><b>[ a - z ]</b></p>
|
|
<p>Stands for the string of characters whose ASCII codes
|
|
run from character <b>a</b> to character <b>z</b>,
|
|
inclusive.</p>
|
|
<p><b>[ a * n ]</b></p>
|
|
<p>Stands for n repetitions of <b>a</b>. If the first
|
|
digit of <b>n</b> is 0, <b>n</b> is considered octal;
|
|
otherwise, <b>n</b> is taken to be decimal. A zero or
|
|
missing <b>n</b> is taken to be huge; this facility is
|
|
useful for padding <i>string2</i>.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>OPTIONS</b></p>
|
|
|
|
<dir>
|
|
<li>Any combination of the options -<b>c</b>, -<b>d</b>, or -<b>s</b>
|
|
may be used:<p>-<b>c</b> Complement the set of characters
|
|
in <i>string1</i> with respect to the universe of
|
|
characters whose ASCII codes are 01 through 0377 octal;</p>
|
|
<p>-<b>d</b> Delete all input characters in <i>string1</i>.</p>
|
|
<p>-<b>s</b> Squeeze all strings of repeated output
|
|
characters that are in <i>string2</i> to single
|
|
characters.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>EXAMPLE</b></p>
|
|
|
|
<dir>
|
|
<li>The following example creates a list of all the words in
|
|
filename one per line in filename2, where a word is taken
|
|
to be a maximal string of alphabetics. The second string
|
|
is quoted to protect `\' from the shell. 012 is the ASCII
|
|
code for NEWLINE.<p><font face="Courier New"><b>tr -cs
|
|
A-Za-z '\012' < filename1 > filename2</b></font></p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>conv</b>(1), <b>more</b>(1)</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>Will not handle ASCII NUL in <i>string1</i> or <i>string2</i>.
|
|
<b>tr</b> always deletes NUL from input.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>unshar - extracts files from shar archives</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>unshar</b> {-overwrite} {-nosort} <i>file1</i> <i>file2</i>
|
|
...</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Unshar</b> is a utility which extracts files from the
|
|
ubiquitous Unix shar archives. It has the following
|
|
advantages over existing unshar utilities:<p>- Small and
|
|
fast</p>
|
|
<p>- Handles many cat and sed formats</p>
|
|
<p>- Allows extraction of subdirectories</p>
|
|
<p>- Understands ./file type filenames</p>
|
|
<p>- Understands file continuation with >></p>
|
|
<p>- Sorts file list by Subject: line</p>
|
|
<p>- Exits cleanly with CTRL-C</p>
|
|
<p><b>Unshar</b> treats quotes and imbedded escape
|
|
sequences intelligently and handles all the cat and sed
|
|
formats the author ever seen, including sed commands
|
|
which strip off more than one letter. There may be some
|
|
formats it won't handle, but I've yet to find them.</p>
|
|
<p>Invoke <b>unshar</b> with as many archive filenames as
|
|
you like. All the files in each archive will be extracted
|
|
into the current directory. If a file already exists, <b>unshar</b>
|
|
asks you how you want to handle it. Entering `Y' will
|
|
overwrite the existing file with the version in the
|
|
archive, `N' will skip past the file without extracting
|
|
it, and `A' will overwrite this file and any other
|
|
existing files without prompting you again. Including the
|
|
-o flag on the command line causes files to always be
|
|
overwritten.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>OPERATION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Unshar</b> scans through each archive specified on the
|
|
command line, looking for lines beginning with `cat' or
|
|
`sed'. All other lines are ignored. In particular, `echo'
|
|
lines are not echoed. This way, you don't get a load of
|
|
messages which are in any case fairly meaningless,
|
|
because the operations they are describing are
|
|
unsupported.<p>When a shar archive contains a file for
|
|
which a full pathname is given (as in source/file.c for
|
|
example) unshar will create whatever directories are
|
|
necessary. It also strips off leading /'s and ./'s, to
|
|
make filenames understandable by GS/OS.</p>
|
|
<p>Occasionally, a shar file distribution will contain a
|
|
file too large to fit into a single shar archive
|
|
(archives are typically limited to around 60K or so for
|
|
transmission over Usenet). One method some archivers use
|
|
to get around this is to split the large file into
|
|
several smaller parts, and use the shell `>>'
|
|
redirection operator to concatenate the parts together
|
|
while extracting the files. In order for this to work
|
|
properly, it is important that the archive files are
|
|
extracted in the correct sequence; otherwise, all the
|
|
pieces will get joined together in the wrong order.</p>
|
|
<p>To assist with this, <b>unshar</b> does a prescan over
|
|
all the files listed on the command line, and checks each
|
|
file for a "Subject:" line. If it finds such a
|
|
line, it scans it looking for any hints as to where the
|
|
file comes in the sequence. Most shar files you feed to
|
|
unshar will be directly from a Usenet sources or binaries
|
|
group, and will include a volume and issue reference on
|
|
the subject line. If <b>unshar</b> can't find such an
|
|
issue reference, it will look for a Part number and use
|
|
that instead.</p>
|
|
<p><b>Unshar</b> then extracts the archives starting with
|
|
the lowest numbered file. This helps to ensure that those
|
|
extra-large files are created correctly. You can tell
|
|
when such a file is being created, because <b>unshar</b>
|
|
says "Extending file" rather than
|
|
"Unsharing file".</p>
|
|
<p>If for some reason you want the files to be unarchived
|
|
in the order listed on the command line, you can specify
|
|
the `-n' (nosort) switch, and no sorting will take place.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>HISTORY</b></p>
|
|
|
|
<dir>
|
|
<li>V1.0 First release.<p>V1.1 Added support for some more
|
|
unusual uses of sed. </p>
|
|
<p>Increased speed, and reduced size slightly.</p>
|
|
<p>Fixed bug that truncated lines longer than 80 chars.</p>
|
|
<p>V1.2 Added support for sorting by Subject: line</p>
|
|
<p>Added support for file appending via >> </p>
|
|
<p>Fixed small bug in detection of disk write errors</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>AUTHOR</b></p>
|
|
|
|
<dir>
|
|
<li>Eddy Carroll (EMAIL: ecarroll@vax1.tcd.ie)<p>Apple //gs
|
|
port by Andy McFadden (fadden@uts.amdahl.com).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>wc - display a count of lines, words and characters</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>wc</b> [ -<b>lwc</b> ] [ <i>filename</i> ... ]</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>wc</b> counts lines, words, and characters in <i>filename</i>
|
|
s, or in the standard input if no filename appears. It
|
|
also keeps a total count for all named files. A word is a
|
|
string of characters delimited by SPACE, TAB, or NEWLINE
|
|
characters.</li>
|
|
</dir>
|
|
|
|
<p><b>OPTIONS</b></p>
|
|
|
|
<dir>
|
|
<li>When <i>filename</i> s are specified on the command line,
|
|
their names will be printed along with the counts.<p>The
|
|
default is -<b>lwc</b> (count lines, words, and
|
|
characters).</p>
|
|
<p>-<b>l</b> Count lines.</p>
|
|
<p>-<b>w</b> Count words.</p>
|
|
<p>-<b>c</b> Count characters.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>EXAMPLE</b></p>
|
|
|
|
<dir>
|
|
<li><font face="Courier New">example% wc $USRMAN/csh.1
|
|
$USRMAN/sh.1 $USRMAN/telnet.1</font><p><font
|
|
face="Courier New">1876 11223 65895
|
|
/usr/share/man/man1/csh.1</font></p>
|
|
<p><font face="Courier New">674 3310 20338
|
|
/usr/share/man/man1/sh.1</font></p>
|
|
<p><font face="Courier New">260 1110 6834
|
|
/usr/share/man/man1/telnet.1</font></p>
|
|
<p><font face="Courier New">2810 15643 93067 total</font></p>
|
|
<p><font face="Courier New">example%</font></p>
|
|
</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>who - who is on the system</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>who</b> [ who-file ] [ am I ]</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Who</b>, without an argument, lists the login name,
|
|
terminal name, and login time for each current UNIX user.<p>Without
|
|
an argument, <b>who</b> examines the <b>/etc/utmp</b>
|
|
file to obtain its information. If a file is given, that
|
|
file is examined. Typically the given file will be <b>/usr/adm/wtmp</b>,
|
|
which contains a record of all the logins since it was
|
|
created. Then <b>who</b> lists logins, logouts, and
|
|
crashes since the creation of the wtmp file. Each login
|
|
is listed with user name, terminal name (with `/dev/'
|
|
suppressed), and date and time. When an argument is
|
|
given, logouts produce a similar line without a user
|
|
name. Reboots produce a line with `x' in the place of the
|
|
device name, and a fossil time indicative of when the
|
|
system went down.</p>
|
|
<p>With two arguments, as in `who am I' (and also `who
|
|
are you'), <b>who</b> tells who you are logged in as.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>FILES</b></p>
|
|
|
|
<dir>
|
|
<li>/etc/utmp</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li>getuid(2), utmp(5)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li><b>yes</b> - be repetitively affirmative</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li><b>yes</b> [ expletive ]</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Yes</b> repeatedly outputs "y", or if <i>expletive</i>
|
|
is given, that is output repeatedly. Termination is by
|
|
interrupt.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>alarm - set and reset alarm timer</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>long int <b>alarm</b>(long
|
|
int <i>seconds</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>alarm sets the counter on the calling process' alarm
|
|
timer to the value specified in <i>seconds</i>. If <i>seconds</i>
|
|
is (long int) 0, the alarm timer is disabled.<p>When an
|
|
alarm timer terminates (by counting down to 0), the
|
|
calling process is sent a SIGALRM signal.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The amount of time previously remaining in the timer is
|
|
returned. No errors are possible.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>signal</b>(2), <b>sigpause</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>dup,dup2 - duplicate open file descriptors</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>dup</b>(int <i>filedes</i>);</p>
|
|
<p>int <b>dup2</b>(int <i>filedes</i>, int <i>filedes2</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>Given the file descriptor of a valid open file, <b>dup</b>
|
|
creates a new file descriptor that is synonymous with <i>filedes</i>.
|
|
The new file descriptor is returned. The second form of
|
|
the call forces an existing file descriptor <i>filedes2</i>
|
|
to refer to the same file as <i>filedes</i>. If <i>filedes2</i>
|
|
already refers to an open file, it is closed first.</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li><b>dup</b> returns the new file descriptor, and <b>dup2</b>
|
|
returns 0 if the calls are successful. In the event of an
|
|
error, -1 is returned and <b>errno</b> is set as follows:<p>[EBADF]
|
|
filedes refers to an invalid file descriptor (not an open
|
|
file)</p>
|
|
<p>[EMFILE] no more files can be opened; process is at
|
|
current limit (32).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork</b>(2), <b>open</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>execve - replace current process with an executable image
|
|
from a file</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>execve</b>(char *<i>pathname</i>,
|
|
char *<i>cmdline</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>execve</b> is the preferred method for loading program
|
|
files to be executed under the GNO system. A new userID
|
|
is allocated for the process, and the GS/OS System Loader
|
|
is used to bring the executable file specified by
|
|
pathname into memory. <i>pathname</i> can be a partial or
|
|
complete path. The executable loaded replaces the
|
|
executable associated with the current process.<p>If the
|
|
executable file does not contain an OMF Stack Segment
|
|
(SEGKIND = $12), a default stack of 4096 bytes is
|
|
allocated to the process. The direct-page pointer is set
|
|
to the bottom of the stack memory (for C programs this is
|
|
irrelevant).</p>
|
|
<p>The parameter <i>cmdline</i> is the list of arguments
|
|
to be passed to the new process (a copy is actually
|
|
passed). C programs parse cmdline automatically, and the
|
|
individual pieces can be accessed through the argc/argv
|
|
arguments to main(). <i>cmdline</i> can be accessed from
|
|
assembly langugage through the X (high-order word of <i>cmdline</i>)
|
|
and Y (low-order word) registers. However, if the
|
|
executable file is of file type S16 ($B3), the <i>cmdline</i>
|
|
argument is ignored and the X&Y registers are set to
|
|
null (i.e. the command line is only passed to an EXE
|
|
executable). The 8 characters "BYTEWRKS" are
|
|
prepended to <i>cmdline</i> before being passed to the
|
|
process (this is the same identifier used by the ORCA
|
|
shell). This Shell Identifier distinguishes the GNO and
|
|
ORCA environments from others that don't support the full
|
|
range of shell calls, and can be accessed from C with the
|
|
library function <b>shellid</b>(). The A register is set
|
|
to the userID allocated for the process.</p>
|
|
<p>GS/OS prefixes 1 and 9 are set to the pathname of the
|
|
directory containing the executable file; if the length
|
|
of the path exceeds 64 characters prefix 1 is set to the
|
|
null prefix (length 0).</p>
|
|
<p>The following information is inherited by the new
|
|
executable: current machine state, controlling TTY,
|
|
process group ID, and prefixes 0 and 8. </p>
|
|
<p>Caught signals are reset to the default action.
|
|
Ignored signals remain ignored across the <b>execve</b>.
|
|
Any signals in the parent's queue are not passed to the
|
|
child, and the child is started with no signals blocked.
|
|
The child inherits all the open files of its parent.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>A successful <b>execve</b> does not return, as the
|
|
current executable is replaced with the one specified in
|
|
the call. If for some reason the call fails, execve
|
|
returns SYSERR (-1), and <b>errno</b> is set to one of
|
|
the following:<p>[ENOENT] the <i>pathname</i> specified
|
|
does not exist</p>
|
|
<p>[EIO] some general I/O error occurred trying to load
|
|
the executable</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>ORCA/C 1.3 and previous ignore any stack space allocated
|
|
for it by the GS/OS Loader (which execve calls) or by
|
|
default in execve. Stack space in ORCA/C programs is
|
|
determined by code in the .root object file, and can be
|
|
set with the #pragma stacksize directive. Read the
|
|
chapter on GNO Compliance in the <i>GNO Kernel Reference
|
|
Manual</i> for more information on this topic. ORCA/C 2.0
|
|
and newer use the system-provided stack space.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>exec</b>(2), <b>fork</b>(2), <b>wait</b>(2), <b>ioctl</b>(2),
|
|
<b>tty</b>(4), <i>GNO Kernel Reference Manual</i></li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>fork - start a new process from inside the current
|
|
application space</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>fork</b>(void *<i>addr</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork</b>'s argument <i>addr</i> is typically the
|
|
address of a C function, although it can be any valid
|
|
address inside the IIGS RAM space. <b>fork</b> creates a
|
|
new entry in the process table, and sets up default
|
|
settings for the new process. The process is allocated 1K
|
|
(1024 bytes) of stack space, and the direct page is set
|
|
to the beginning of this memory. The process is executed
|
|
in 16-bit full native mode, and the registers upon entry
|
|
to the routine are set as follows:<p>A the userID
|
|
assigned to the process</p>
|
|
<p>X 0</p>
|
|
<p>Y 0</p>
|
|
<p>The child inherits the memory shadowing and machine
|
|
state parameters of the parent, as well as signal
|
|
blocking information and the ID of the controlling TTY.
|
|
In addition, the child inherits all the open files of its
|
|
parent.</p>
|
|
<p>A forked process may share code with other children or
|
|
the parent. However, this is only allowed in a forward
|
|
manner; any forked process that exits by function return
|
|
will be terminated. Note that any shared global variables
|
|
will need to be moderated with some type of mutual
|
|
exclusion, either the kernel semaphore(2) routines or
|
|
custom routines. This includes C stdio routines.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork</b> returns the process ID of the child, or -1
|
|
(SYSERR) if an error occurs, in which case <b>errno</b>
|
|
is set as follows:<p>[ENOMEM] not enough memory to create
|
|
the new process</p>
|
|
<p>[EAGAIN] all process slots full; no more can be
|
|
created</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li>There is no way to pass parameters directly to a child
|
|
with <b>fork</b>(). Use <b>fork2</b>() instead.</li>
|
|
</dir>
|
|
|
|
<p><b>CAVEATS</b></p>
|
|
|
|
<dir>
|
|
<li>Most UNIX <b>fork</b>s take no parameters; they copy the
|
|
entire address space of the calling process and return
|
|
with a different value in the parent and child. Due to
|
|
hardware limitations, this sort of manipulation isn't
|
|
possible on the IIgs. UNIX programs utilizing <b>fork</b>
|
|
will have to be modified slightly to work under GNO.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork2</b>(2), <b>exec</b>(2), <b>execve</b>(2), <b>wait</b>(2),
|
|
<b>screate</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>getpid, getpgrp, getppid - return information about
|
|
processes</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>getpid</b>(void);</p>
|
|
<p>int <b>getpgrp</b>(int <i>pid</i>);</p>
|
|
<p>int <b>getppid</b>(void);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>The process ID is a unique value associated with a
|
|
process, and is needed for many system calls. pid's can
|
|
range from 0 (Kernel Null Process) to 32767. Some
|
|
programs use <b>getpid</b> to seed random number
|
|
generators. A much better approach on the IIGS is to use
|
|
the horizontal and vertical positions of the electron
|
|
gun, which can be obtained by reading the word value at
|
|
absolute memory location $E0C02E.<p><b>getpgrp</b>
|
|
returns the process group ID of the specified process, <i>pid</i>.
|
|
This function is usually used when you wish to send a
|
|
signal to all members of a process group using <b>kill</b>(2).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li><b>getpid</b>: The process ID of the caller is returned.
|
|
No errors are possible.<p><b>getppid</b>: The process ID
|
|
of the caller's parent is returned. No errors are
|
|
possible.</p>
|
|
<p><b>getpgrp</b>: The process group ID of the specified
|
|
process is returned. In the event of an error, getpgrp
|
|
returns -1 and sets <b>errno</b> to the appropriate error
|
|
code:</p>
|
|
<p>[ESRCH] pid is not a valid process ID</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li><b>getpgrp</b>() is provided solely for compatibility
|
|
with previous versions of the UNIX operating system. The
|
|
new Job Control interface should be used exclusively in
|
|
new software.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork</b>(2), <b>job control</b>(2), <b>ioctl</b>(2), <i>GNO
|
|
Kernel Reference Manual</i></li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>getuid, geteuid, getgid, getegid - get user and group
|
|
identity<p>getpgrp - get process group</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <sys/types.h><p>uid_t = <b>getuid</b>(void)</p>
|
|
<p>uid_t = <b>geteuid</b>(void)</p>
|
|
<p>gid_t = <b>getgid</b>(void)</p>
|
|
<p>gid_t = <b>getegid</b>(void)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Getuid</b> returns the real user ID of the current
|
|
process, <b>geteuid</b> the effective user ID. The real
|
|
user ID identifies the person who is logged in. The
|
|
effective user ID gives the process additional
|
|
permissions during execution of "set-user-ID"
|
|
mode processes, which use getuid to determine the
|
|
real-user-id of the process that invoked them.<p><b>Getgid</b>
|
|
returns the real group ID of the current process, <b>getegid</b>
|
|
the effective group ID. The real group ID is specified at
|
|
login time. The effective group ID is more transient, and
|
|
determines additional access permission during execution
|
|
of a ``set-group-ID'' process, and it is for such
|
|
processes that getgid is most useful.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li>The <b>setr</b>*() functions are not currently
|
|
implemented in GNO/ME, because set-uid and set-group-ID
|
|
behavior is specific to the UNIX filesystem.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>setreuid</b>(2), <b>setregid</b>(2), <b>setgid</b>(3),
|
|
<b>tty</b>(4)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>intro - introduction to GNO system calls</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>This section describes, in alphabetical order, the system
|
|
calls and kernel interfaces available for GNO. Certain
|
|
distinctions of purpose are made in the headings. </li>
|
|
</dir>
|
|
|
|
<p><b>Manual Page Command Syntax</b></p>
|
|
|
|
<dir>
|
|
<li>Unless otherwise noted, calls described in the <b>SYNOPSIS</b>
|
|
section of a manual page accept parameters and require
|
|
the<p>name [- option ...] [ cmdarg ...]</p>
|
|
<p>where:</p>
|
|
<p>[] Surround an option or cmdarg that is not required.</p>
|
|
<p>... Indicates multiple occurrences of the option or
|
|
cmdarg.</p>
|
|
<p>name The name of an executable file.</p>
|
|
<p>option (Almost always preceded by a "-".)</p>
|
|
<p>noargletter ... or,</p>
|
|
<p>argletter optarg [,...]</p>
|
|
<p>noargletter A single letter representing an option
|
|
without an option-argument. Note that more than one
|
|
noargletter option can be grouped after one
|
|
"-".</p>
|
|
<p>argletter A single letter representing an option
|
|
requiring an option-argument.</p>
|
|
<p>optarg An option-argument (character string)
|
|
satisfying a preceding argletter. Note that groups of
|
|
optargs following an argletter must be separated by white
|
|
space and quoted.</p>
|
|
<p>cmdarg Path name (or other command argument) not
|
|
beginning with a "-", or "-" by
|
|
itself indicating the standard input.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><i>GNO/ME Kernel Reference Manual</i></li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>ioctl - control device</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <sys/ioctl.h><p>int <b>ioctl</b>(int <i>fd</i>,
|
|
unsigned long <i>request</i>, void *<i>argp</i>)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>Ioctl</b> performs a variety of functions on open file
|
|
descriptors. In particular, many operating
|
|
characteristics of character special files (e.g.
|
|
terminals) may be controlled with <b>ioctl</b> requests.
|
|
The writeups of various devices in section 4 discuss how <b>ioctl</b>
|
|
applies to them.<p>An <b>ioctl</b> <i>request</i> has
|
|
encoded in it whether the argument is an "in"
|
|
parameter or "out" parameter, and the size of
|
|
the argument argp in bytes. Macros and defines used in
|
|
specifying an <b>ioctl</b> request are located in the
|
|
file <sys/ioctl.h>.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>If an error has occurred, a value of -1 is returned and <b>errno</b>
|
|
is set to indicate the error.</li>
|
|
</dir>
|
|
|
|
<p><b>ERRORS</b></p>
|
|
|
|
<dir>
|
|
<li><b>Ioctl</b> will fail if one or more of the following
|
|
are true:<p><font face="Courier New">[EBADF]</font> <i>Fd</i>
|
|
is not a valid descriptor.</p>
|
|
<p><font face="Courier New">[ENOTTY]</font> <i>Fd</i> is
|
|
not associated with a character special device.</p>
|
|
<p><font face="Courier New">[ENOTTY]</font> The specified
|
|
request does not apply to the kind of object that the
|
|
descriptor fd references.</p>
|
|
<p><font face="Courier New">[EINVAL]</font> <i>Request</i>
|
|
or <i>argp</i> is not valid.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>execve</b>(2), <b>tty</b>(4)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>tcnewpgrp, settpgrp, tctpgrp - interface for the new job
|
|
control model</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>tcnewpgrp</b>(int <i>fdtty</i>);</p>
|
|
<p>int <b>settpgrp</b>(int <i>fdtty</i>);</p>
|
|
<p>int <b>tctpgrp</b>(int <i>fdtty</i>, int <i>pid</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>The job control interface is used to control what
|
|
processes are ``in the foreground'' on a particular
|
|
terminal. Every tty has a process group. Each process is
|
|
a member of a process group. A process is a foreground
|
|
process on a tty if and only if that process and the
|
|
terminal belong to the same process group. Certain
|
|
characters typed on a tty with a nonzero process group
|
|
produce signals sent to every process which is a member
|
|
of the group (e.g. ^C). <p>A process is suspended
|
|
(stopped) if it performs a sufficiently invasive
|
|
operation on a tty with a different process group. This
|
|
includes these job control calls, reads from a terminal,
|
|
and writes to a terminal if configured to do so with <b>ioctl</b>(2).
|
|
When a tty file is first opened, it is assigned process
|
|
group 0; init has process group 0. As init launches login
|
|
processes on various ttys, it assigns process groups to
|
|
those ttys and processes.</p>
|
|
<p><b>tcnewpgrp</b>(fdtty): Allocates a new process group
|
|
and assigns it to the terminal referred to by fdtty. If
|
|
the calling process is not in the foreground, it is sent
|
|
SIGTTOU.</p>
|
|
<p><b>settpgrp</b>(fdtty): Sets the current process to
|
|
have the same process group as fdtty.</p>
|
|
<p><b>tctpgrp</b>(fdtty,pid): Sets the tty to the same
|
|
process group as pid, where pid is the current process or
|
|
a descendant of it. </p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The calls will return 0 if no error occurs; otherwise,
|
|
they'll return -1 and set <b>errno</b> to one of the
|
|
following:<p><font face="Courier New">[EBADF]</font> <i>fdtty</i>
|
|
is not a valid file descriptor</p>
|
|
<p><font face="Courier New">[ENOTTY]</font> <i>fdtty</i>
|
|
does not refer to a terminal file</p>
|
|
<p><font face="Courier New">[ESRCH]</font> <i>pid</i> is
|
|
not a valid process identifier</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li>Following are some example uses of the job control
|
|
interface.<p>• Forking a pipeline in a job-control
|
|
shell: The shell starts with <b>tcnewpgrp</b>(fdtty), so
|
|
that the tty is in the new process group before there are
|
|
even any children. It then forks each process in the
|
|
pipeline. Each process does <b>settpgrp</b>(fdtty), thus
|
|
joining the new process group.</p>
|
|
<p>• Handling a stopped child process: When the
|
|
shell sees that a pipeline has stopped or exited, it does
|
|
<b>tctpgrp</b>(fdtty,getpid()) to set the tty to its own
|
|
process group. To resume the pipeline it does <b>tctpgrp</b>(fdtty,pid)
|
|
where pid is one of the child processes, then sends
|
|
SIGCONT.</p>
|
|
<p>• Starting a process under a new tty: When, for
|
|
instance, telnetd wants to grab a pseudo-tty, it opens
|
|
the pty and forks a child process. The child does <b>tcnewpgrp</b>(fdtty)
|
|
to give the tty a real process group, then <b>settpgrp</b>(fdtty)
|
|
to place itself into the foreground.</p>
|
|
<p>Security under this scheme is trivial. There is no way
|
|
a process can join a process group except by settpgrp(),
|
|
and that requires a descriptor open to a tty with that
|
|
pgrp. To make a tty have that pgrp requires either <b>tcnewpgrp</b>(),
|
|
in which case nobody else is using the pgrp, or <b>tctpgrp</b>(),
|
|
which reduces to the first problem of having a process in
|
|
the process group. End of security proof. (Wasn't that
|
|
easy?) Note that `using' must be defined as use both by
|
|
ttys and by processes; the system keeps a table of pgrps,
|
|
each with a total tty + process reference count. When the
|
|
reference count reaches zero, the pgrp is automatically
|
|
deallocated.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>ioctl</b>(2), <b>tty</b>(4), <b>signal</b>(2), <b>kill</b>(2),
|
|
<i>GNO Shell Reference Manual</i></li>
|
|
</dir>
|
|
|
|
<p><b>CREDITS</b></p>
|
|
|
|
<dir>
|
|
<li>This job control interface was designed by Dan Bernstein
|
|
(brnstnd@kramden.acf.nyu.edu). He was inspired by Chris
|
|
Torek, and dedicated the system to Mark Teitelbaum. The
|
|
text of this manpage is derived from his original
|
|
specifications.<p>The GNO/ME implementation was written
|
|
strictly from specs.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>kill - send a signal to a process</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>kill</b>(int <i>pid</i>,
|
|
int <i>sig</i>)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>kill</b> is used to send a signal to a process or
|
|
group of processes. Signals are software interrupts; they
|
|
act just like hardware interrupts and can also be used
|
|
for basic IPC (Inter-process communication). The various
|
|
signals are described in <b>signal</b>(2).<p><i>sig</i>
|
|
can be a signal number, or it can be 0, in which case no
|
|
signal is sent, but error checking is done (this can be
|
|
used to verify a process ID). If <i>sig</i> has been
|
|
blocked (<b>sigblock</b>(2)), the signal is deferred
|
|
until it is unblocked, and <b>kill</b> returns
|
|
immediately. Any previously pending signals of the same <i>sig</i>
|
|
are lost (i.e. signals are not stacked).</p>
|
|
<p>If <i>pid</i> is 0, the signal is sent to all
|
|
processes with the same process group ID as the caller,
|
|
except for system processes.</p>
|
|
<p>Processes may signal themselves, in which case the
|
|
signal handler is invoked immediately (if one is
|
|
installed).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>Normally <b>kill</b> returns SYSOK (0). The following
|
|
conditions can cause <b>kill</b> to return SYSERR (-1):<p><font
|
|
face="Courier New">[ESHRC]</font> <i>pid</i> does not
|
|
correspond to an existing process</p>
|
|
<p><font face="Courier New">[EINVAL]</font> <i>sig</i>
|
|
specifies an invalid signal number</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>sigblock</b>(2), <b>signal</b>(2), <b>wait</b>(2)</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>Do not attempt to send signals from inside a CDA (Classic
|
|
Desk Accessory) or interrupt handler.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>pipe - create an interprocess communication channel</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>pipe</b>(int <i>filedes[2]</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>The <b>pipe</b> system call creates an I/O mechanism
|
|
called a pipe. The file descriptors returned can be used
|
|
in read and write operations. When the pipe is written
|
|
using the descriptor <i>filedes[1]</i> up to 4096 bytes
|
|
of data are buffered before the writing process is
|
|
suspended. A read using the descriptor <i>filedes[0]</i>
|
|
will pick up the data.<p>It is assumed that after the
|
|
pipe has been set up, two (or more) cooperating processes
|
|
(created by subsequent fork calls) will pass data through
|
|
the pipe with Read and Write calls.</p>
|
|
<p>The shell has a syntax to set up a linear array of
|
|
processes connected by pipes.</p>
|
|
<p><b>Read</b> calls on an empty pipe (no buffered data)
|
|
with only one end (all write file descriptors closed)
|
|
returns an end-of-file.</p>
|
|
<p>A signal (SIGPIPE) is generated if a write on a pipe
|
|
with only one end is attempted.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The function value zero is returned if the pipe was
|
|
created; -1 if an error occurred.</li>
|
|
</dir>
|
|
|
|
<p><b>ERRORS</b></p>
|
|
|
|
<dir>
|
|
<li>The pipe call will fail if:<p><font face="Courier New">[EMFILE]</font>
|
|
Too many descriptors are active.</p>
|
|
<p><font face="Courier New">[ENFILE]</font> The system
|
|
file table is full.</p>
|
|
<p><font face="Courier New">[EFAULT]</font> The fildes
|
|
buffer is in an invalid area of the process's address
|
|
space.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><i>GNO Shell Users Manual</i>, <b>read</b>(2), <b>write</b>(2),
|
|
<b>fork</b>(2)</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>Should more than 4096 bytes be necessary in any pipe
|
|
among a loop of processes, deadlock will occur.</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li>In the above text, mention is made to UNIX read and write
|
|
calls. On the Apple IIgs, these refer to any system calls
|
|
that do I/O, namely GS/OS ReadGS, WriteGS; TextTools
|
|
calls; and C library I/O calls such as read, fread, etc.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>screate, sdelete, swait, ssignal - semaphore operations</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>swait</b>(int <i>sem</i>);</p>
|
|
<p>int <b>ssignal</b>(int <i>sem</i>);</p>
|
|
<p>int <b>screate</b>(int <i>count</i>);</p>
|
|
<p>int <b>sdelete</b>(int <i>sem</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>screate</b> is used to allocate a semaphore from the
|
|
kernel semaphore manager. Semaphores are the most basic
|
|
form of interprocess communication, and these routines
|
|
provide the power necessary to solve a large number of
|
|
synchronization and communication problems. (See an
|
|
Operating Systems text).<p>The initial <i>count</i>
|
|
determines how many times <b>swait</b> can be called
|
|
before processes are blocked. <i>count</i> must be >=
|
|
0, and is usually set to 1. <b>screate</b> returns a
|
|
semaphore ID number as an integer. This ID must be used
|
|
in all the other semaphore calls.</p>
|
|
<p><b>sdelete</b> releases the specified semaphore, and
|
|
returns all processes that were blocked to a ready state.</p>
|
|
<p><b>swait</b> decrements the value of the semaphore
|
|
(initially specified by <i>count</i> ) by 1. If the
|
|
semaphore count is less than zero, the process is blocked
|
|
and queued for release by <b>ssignal</b>.</p>
|
|
<p><b>ssignal</b> increments the semaphore count by one.
|
|
If the semaphore count is less than zero, <b>ssignal</b>
|
|
releases arbitrarily a process that had been blocked;
|
|
FIFO operation is not guaranteed.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>All the functions return SYSERR (-1) if an error occurs,
|
|
and an OK (0) if no error occurs.</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>There is currently no mechanism for deallocating
|
|
semaphores that are orphaned by abnormal process
|
|
termination.</li>
|
|
</dir>
|
|
|
|
<p><b>HISTORY</b></p>
|
|
|
|
<dir>
|
|
<li>These semaphore routines were designed for XINU, written
|
|
by Douglas Comer.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>setdebug - set debugging output options</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <gno/gno.h><p>int <b>setdebug</b>(int <i>options</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>setdebug</b> enables and disables various debugging
|
|
routines built into the kernel. The routines display
|
|
useful debugging information to stderr (except for
|
|
dbgSIG, see BUGS). Debug output is enabled by setting the
|
|
corresponding bit in options, according to the following
|
|
table. To turn off all debugging output, options should
|
|
be set to 0. The various debug options are #defined in
|
|
<gno/gno.h>.<p><font face="Courier New">dbgGSOS</font>
|
|
prints out the call numbers of any GS/OS or ORCA/shell
|
|
calls that are made. The number is printed in hexadecimal
|
|
format and is prefixed with a '$' character. For this and
|
|
the other GS/OS call debug options, the entire call
|
|
sequence is enclosed in parenthesis '()' to ease tracing
|
|
multiple levels of calls.</p>
|
|
<p><font face="Courier New">dbgPATH</font> If this flag
|
|
is set, every time a filename argument to a GS/OS or
|
|
shell call is fully expanded the expanded version is
|
|
displayed as follows: "<font face="Courier New">EP: <fullpath></font>".</p>
|
|
<p><font face="Courier New">dbgERROR</font> For every
|
|
GS/OS call that is made, if an error occurs the error
|
|
code is printed in inverse lettering in hexidecimal
|
|
format. The code is prefixed with a '#' to distinguish
|
|
the error code from a call code on terminals that do not
|
|
support inverse mode. If no error occurs on the call, no
|
|
code is printed. This option has no effect unless <font
|
|
face="Courier New">dbgGSOS</font> is also enabled.</p>
|
|
<p><font face="Courier New">dbgSIG</font> This flag
|
|
enables signal tracing. Each time a signal is sent,
|
|
whether by kill(2), job control or keyboard, the signal
|
|
number and target process is displayed. The format is:
|
|
"<font face="Courier New">kill (-signum): pid: tpid</font>".</p>
|
|
<p><font face="Courier New">dbgSYSCALL</font> The
|
|
parameter lists to common system calls are displayed by
|
|
this option flag. The actual format of the output varies
|
|
from call to call. The calls that currently support this
|
|
flag are <b>execve</b>(2), <b>fork</b>(2), and the job
|
|
control routines.</p>
|
|
<p><font face="Courier New">dbgPBLOCK</font> The memory
|
|
address of GS/OS and Shell parameter blocks is printed
|
|
for each call. As with <font face="Courier New">dbgERROR</font>,
|
|
this option has no effect unless <font face="Courier New">dbgGSOS</font>
|
|
is also enabled.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li><b>setdebug</b> returns the previous value of the debug
|
|
options word.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>fork</b>(2),<b>execve</b>(2),<b>ioctl</b>(2),<b>kill</b>(2)</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>Due to problems associated with signals that are sent
|
|
during process termination, <font face="Courier New">dbgSIG</font>
|
|
prints its information to standard output instead of
|
|
standard error.</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>sigblock,sigmask - temporarily block signals</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <signal.h><p>long <b>sigblock</b>(long <i>mask</i>);</p>
|
|
<p>#define <b>sigmask</b>(<i>signum</i>)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>sigblock</b> is used to temporarily block the
|
|
reception of signals. The input parameter <i>mask</i> is
|
|
a bit vector that specifies which signals are to be
|
|
blocked; a 1 in a bit n will block signal n+1. The mask
|
|
is bitwise-ored with the current signal mask to create
|
|
the new signal mask.<p><b>sigmask</b> is a macro that can
|
|
be used to calculate signal masks for <b>sigblock</b>. It
|
|
takes a signal number (<i>signum</i>) as an argument and
|
|
returns a mask that can then be passed to <b>sigblock</b>.</p>
|
|
<p>If a signal is sent to a process but is blocked, the
|
|
event is recorded for later release by <b>sigsetmask</b>(2).
|
|
Blocked signals are not stacked; further occurrences of a
|
|
blocked signal will overwrite any previous pending signal
|
|
of the same <i>signum</i>.</p>
|
|
<p>It is not possible to block SIGKILL, SIGCONT, or
|
|
SIGSTOP. This restriction is silently enforced by the
|
|
system.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The previous value of the signal mask is returned.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>kill</b>(2), <b>sigsetmask</b>(2), <b>signal</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>signal - a simplified software signal interface</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <signal.h><p>void (*<b>signal</b>(int <i>sig</i>;
|
|
void (*<i>func</i>(void))(void)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>Signals are a basic form of IPC (inter-process
|
|
communication), and are generally used to notify a
|
|
process of some atypical event (although there is little
|
|
restriction on actual use). For example, signals are sent
|
|
in each of the following situations: user typing certain
|
|
chars at a terminal (^C, ^Z, etc.); execution of an
|
|
invalid instruction; by request of another process (<b>kill</b>);
|
|
stack overflow; a process making an input request while
|
|
running in the background; an attempt to write to a pipe
|
|
with no reader.<p>Most signals cause termination, unless
|
|
a handler is installed, or the signal is set to be
|
|
ignored. Certain signals cannot have their default action
|
|
modified; the system silently enforces this restriction.
|
|
The following is a list of signals and default actions
|
|
(taken from signal.h).</p>
|
|
<p>SIGHUP 1 hangup</p>
|
|
<p>SIGINT 2 interrupt</p>
|
|
<p>SIGQUIT 3 quit</p>
|
|
<p>SIGILL 4 illegal instruction</p>
|
|
<p>SIGTRAP 5 trace trap</p>
|
|
<p>SIGABRT 6 abort (generated by abort(3) routine) </p>
|
|
<p>SIGEMT 7 emulator trap </p>
|
|
<p>SIGFPE 8 arithmetic exception </p>
|
|
<p>SIGKILL 9 kill (cannot be caught, blocked, or ignored)
|
|
</p>
|
|
<p>SIGBUS 10 bus error </p>
|
|
<p>SIGSEGV 11 segmentation violation </p>
|
|
<p>SIGSYS 12 bad argument to system call </p>
|
|
<p>SIGPIPE 13 write on a pipe or other socket with no one
|
|
to read it </p>
|
|
<p>SIGALRM 14 alarm clock </p>
|
|
<p>SIGTERM 15 software termination signal </p>
|
|
<p>SIGURG 16@ urgent condition present on socket </p>
|
|
<p>SIGSTOP 17 | + stop (cannot be caught, blocked, or
|
|
ignored) </p>
|
|
<p>SIGTSTP 18 | + stop signal generated from keyboard </p>
|
|
<p>SIGCONT 19@ continue after stop (cannot be blocked) </p>
|
|
<p>SIGCHLD 20@ child status has changed </p>
|
|
<p>SIGCLD 20 System V name for SIGCHLD </p>
|
|
<p>SIGTTIN 21 | + background read attempted from control
|
|
terminal </p>
|
|
<p>SIGTTOU 22 | + background write attempted to control
|
|
terminal </p>
|
|
<p>SIGIO 23@ input/output possible on a file descriptor </p>
|
|
<p>SIGPOLL SIGIO System V name for SIGIO </p>
|
|
<p>SIGXCPU 24 exceeded CPU time limit </p>
|
|
<p>SIGUSR1 30 user defined signal 1 </p>
|
|
<p>SIGUSR2 31 user defined signal 2 </p>
|
|
<p>If <i>func</i> is SIG_DFL, the defult action for the
|
|
signal is reinstalled. This is normally termination if
|
|
the signal isn't ignored or caught. Signals marked with
|
|
an @ are discarded, and signals marked with | + cause the
|
|
process to stop. If <i>func</i> is SIG_IGN, any future
|
|
occurences of the signal are discarded, as well as any
|
|
pending instances. Any other value is treated as the
|
|
address of a handler routine. The system will block
|
|
further occurences of the signal before the handler is
|
|
called, and will unblock the signal automatically upon
|
|
return from the handler. The handler remains installed
|
|
after return, unlike earlier UNIX signal facilities.</p>
|
|
<p>If a signal occurs during certain system calls (<b>wait</b>(),
|
|
and input from a TTY), the call is automatically
|
|
restarted upon return from the handler.</p>
|
|
<p>A forked child inherits all signal information,
|
|
including pending signals and blocking and handler
|
|
information. <b>exec</b>() and <b>execve</b>() restore
|
|
all signal information to defaults and purge pending
|
|
signals.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>NOTES</b></p>
|
|
|
|
<dir>
|
|
<li>The signal handler should be defined as follows:<p>void <b>handler</b>
|
|
(int <i>sig</i>, int <i>code</i>)</p>
|
|
<p><i>sig</i> is the signal that invoked the handler, and
|
|
<i>code</i> is additional information about the interrupt
|
|
condition. Currently, <i>code</i> is always 0. The
|
|
handler should probably also be compiled using the
|
|
#pragma databank 1 directive, in the event the signal
|
|
handler is not in the same bank as the C global data
|
|
segment (the handler is called with the data bank equal
|
|
to the program bank).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The previous action is returned on a successful call.
|
|
Otherwise, -1 is returned. <font face="Courier New">[EINVAL]</font>
|
|
will occur on any of the following conditions:<p>sig
|
|
specifies an invalid signal number.</p>
|
|
<p>An attempt is made to ignore or supply a handler for
|
|
SIGKILL or SIGSTOP.</p>
|
|
<p>An attempt is made to ignore SIGCONT (by default
|
|
SIGCONT is ignored).</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>CAVEATS</b></p>
|
|
|
|
<dir>
|
|
<li>ORCA/C already provides a signal() function, but it
|
|
doesn't do a whole lot. GNO's signal.h file replaces the
|
|
one that comes with ORCA.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>execve</b>(2), <b>fork</b>(2), <b>kill</b>(2), <b>sigblock</b>(2),
|
|
<b>sigsetmask</b>(2), <b>wait</b>(2), <b>tty</b>(4)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>sigpause - suspend process until a signal arrives</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <signal.h><p>int <b>sigpause</b>(long int <i>mask</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>sigpause</b> suspends execution of the calling process
|
|
until a signal arrives. The <i>mask</i> parameter is
|
|
assigned to the set of blocked signals (<b>sigsetmask</b>),
|
|
and then the process is paused. When a signal arrives,
|
|
the regular signal handler (if any) is executed, and then
|
|
the original signal mask is restored before returning to
|
|
the caller. Usually <i>mask</i> is 0 (zero) to pause
|
|
until any signal arrives.<p><b>sigpause</b> is normally
|
|
used in situations where one must protect a critical
|
|
section. A typical use begins with sigblock to block a
|
|
signal (and enable mutual exclusion); variables modified
|
|
on the occurrence of that signal are then manipulated,
|
|
code is executed, etc. To end the critical section and
|
|
wait for more work, sigpuase is called.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li><b>sigpause</b> always returns an error (-1) and sets <b>errno</b>
|
|
to EINTR.</li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>signal</b>(2), <b>sigblock</b>(2), <b>sigsetmask</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>sigsetmask - set signal mask</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <signal.h><p>long <b>sigsetmask</b>(long <i>mask</i>);</p>
|
|
<p>#define <b>sigmask</b>(<i>signum</i>)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>sigsetmask</b> is usually used to restore signal masks
|
|
after modification by <b>sigblock</b>. The parameter mask
|
|
is the absolute value the process signal mask will be set
|
|
to (compare to sigblock, which adds the argument to the
|
|
set of blocked signals).<p>If there are pending instances
|
|
of signals which become unblocked by the <b>sigsetmask</b>
|
|
call, they are 'released' into the system signal queue
|
|
and their 'pending' status is cleared. The system signal
|
|
queue is maintained by the kernel null process, and is
|
|
used in situations where signals could not normally be
|
|
sent (such as interrupt handlers).</p>
|
|
<p><b>sigmask</b> is a macro that can be used to
|
|
calculate signal masks for <b>sigsetmask</b>. It takes a
|
|
signal number, as listed in <b>signal</b>(2), as an
|
|
argument and returns a mask corresponding to that signal.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>The previous value of the signal mask is returned.</li>
|
|
</dir>
|
|
|
|
<p><b>CAVEATS</b></p>
|
|
|
|
<dir>
|
|
<li>If somehow the process re-blocks a signal released by <b>sigsetmask</b>
|
|
before the system signal queue processes it, it will be
|
|
blocked and marked as pending. This can happen if a
|
|
signal handler makes a <b>sigblock</b> call. </li>
|
|
</dir>
|
|
|
|
<p><b>SEE ALSO</b></p>
|
|
|
|
<dir>
|
|
<li><b>kill</b>(2), <b>sigblock</b>(2), <b>signal</b>(2)</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>stat, fstat, lstat - return status information on
|
|
indicated files</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <sys/stat.h><p>int <b>stat</b>(const char
|
|
*<i>filename</i>, struct stat *<i>s_buf</i>);</p>
|
|
<p>int <b>fstat</b>(int <i>filedes</i>, struct stat *<i>s_buf</i>);</p>
|
|
<p>int <b>lstat</b>(const char *<i>filename</i>, struct
|
|
stat *<i>s_buf</i>);</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li>These calls are used to retreive status information about
|
|
files. They do much the same thing as the GS/OS call
|
|
GetFileInfo, except that they return the information in a
|
|
format compatible with UNIX's stat calls, and also
|
|
provide information about pipes and GNO Character
|
|
Devices.<p><b>stat</b> takes arguments <i>filename</i>, a
|
|
NUL-terminated string naming the file to get information
|
|
on, and <i>s_buf</i>, a pointer to a <font
|
|
face="Courier New">stat</font> structure, defined in
|
|
<sys/stat.h>. <i>filename</i> can be a partial or a
|
|
complete path. The miscellaneous types in <font
|
|
face="Courier New">struct stat</font>, below, are defined
|
|
in <sys/types.h>, automatically included by stat.h.</p>
|
|
<p><font size="2" face="Courier New">struct stat {</font></p>
|
|
<p><font size="2" face="Courier New">dev_t st_dev; /* ID
|
|
number of device file resides on */</font></p>
|
|
<p><font size="2" face="Courier New">ino_t st_ino; /*
|
|
inode number of file */</font></p>
|
|
<p><font size="2" face="Courier New">unsigned short
|
|
st_mode; /* type of file and mode */</font></p>
|
|
<p><font size="2" face="Courier New">short st_nlink; /*
|
|
number of links to file = 0 */</font></p>
|
|
<p><font size="2" face="Courier New">uid_t st_uid; /*
|
|
user id = 0 */</font></p>
|
|
<p><font size="2" face="Courier New">gid_t st_gid; /*
|
|
group id = 0 */</font></p>
|
|
<p><font size="2" face="Courier New">dev_t st_rdev; /*
|
|
device type ID */</font></p>
|
|
<p><font size="2" face="Courier New">off_t st_size; /*
|
|
length of file in bytes */</font></p>
|
|
<p><font size="2" face="Courier New">time_t st_atime; /*
|
|
last access time (same as mod time on Apple IIGS) */</font></p>
|
|
<p><font size="2" face="Courier New">int st_spare1; /*
|
|
reserved */</font></p>
|
|
<p><font size="2" face="Courier New">time_t st_mtime; /*
|
|
last modification time */</font></p>
|
|
<p><font size="2" face="Courier New">int st_spare2; /*
|
|
reserved */</font></p>
|
|
<p><font size="2" face="Courier New">time_t st_ctime; /*
|
|
file creation time */</font></p>
|
|
<p><font size="2" face="Courier New">int st_spare3; /*
|
|
reserved */</font></p>
|
|
<p><font size="2" face="Courier New">long st_blksize; /*
|
|
size in bytes of blocks on filesystem */</font></p>
|
|
<p><font size="2" face="Courier New">long st_blocks; /*
|
|
number of blocks file uses */</font></p>
|
|
<p><font size="2" face="Courier New">long st_spare4[2];
|
|
/* reserved */</font></p>
|
|
<p><font size="2" face="Courier New">};</font></p>
|
|
<p>The items marked 'reserved' are not currently used but
|
|
are reserved for future expansion; do not use these
|
|
fields for any reason. <font face="Courier New">st_dev</font>
|
|
is the device number the file resides on. This number is
|
|
the same as the GS/OS device ID number. <font
|
|
face="Courier New">st_rdev</font> is not currently used,
|
|
but may in the future designate a device type code.</p>
|
|
<p><font face="Courier New">st_mode</font> is a bit field
|
|
representing access mode and type of the file. The flags
|
|
in <font face="Courier New">st_mode</font> are as
|
|
follows:</p>
|
|
<p>#define S_IFDIR 0040000 /* directory */</p>
|
|
<p>#define S_IFCHR 0020000 /* character special */</p>
|
|
<p>#define S_IFBLK 0060000 /* block special */</p>
|
|
<p>#define S_IFREG 0100000 /* regular */</p>
|
|
<p>#define S_IFLNK 0120000 /* symbolic link */</p>
|
|
<p>#define S_IFSOCK 0140000 /* socket or pipe */</p>
|
|
<p>#define S_IREAD 0000400 /* read permission, owner */</p>
|
|
<p>#define S_IWRITE 0000200 /* write permission, owner */</p>
|
|
<p>#define S_IEXEC 0000100 /* file is an executable,
|
|
owner */</p>
|
|
<p><b>fstat</b> is similar to <b>stat</b> except the
|
|
argument is an open file descriptor <i>filedes</i>. If <i>filedes</i>
|
|
refers to a character device or pipe, the entire <font
|
|
face="Courier New">s_buf</font> is set to 0 and only <font
|
|
face="Courier New">st_mode</font> and <font
|
|
face="Courier New">st_dev</font> are set.</p>
|
|
<p><b>lstat</b> is similar to <b>stat</b>, but if the <i>filename</i>
|
|
is a link then information is returned about the link
|
|
file instead of the file linked to.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>If the call completes without mishap, stat returns a 0.
|
|
If an error occurs, <b>stat</b> returns -1 and sets errno
|
|
to one of the following:<p><font face="Courier New">[ENOENT]</font>
|
|
<i>filename</i> does not specify an existing file or
|
|
directory</p>
|
|
<p><font face="Courier New">[ENOTDIR]</font> an element
|
|
of <i>filename</i> is not an expected subdirectory</p>
|
|
<p><b>fstat</b> can additionally return </p>
|
|
<p><font face="Courier New">[EBADF]</font> <i>filedes</i>
|
|
does not refer to an open file descriptor</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>BUGS</b></p>
|
|
|
|
<dir>
|
|
<li>GNO does not yet support hard or symbolic file links on
|
|
the IIGS. Therefore, <b>lstat</b> operates exactly like
|
|
stat. But if there's a case where <b>lstat</b> might be
|
|
appropriate at a time when links are supported, then use
|
|
lstat instead and be ready for the future.<p><b>fstat</b>
|
|
doesn't do anything clever with all the unused fields in <font
|
|
face="Courier New">struct stat</font> when its argument
|
|
is a pipe or terminal.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<hr>
|
|
|
|
<p><b>NAME</b></p>
|
|
|
|
<dir>
|
|
<li>statfs - get file system statistics</li>
|
|
</dir>
|
|
|
|
<p><b>SYNOPSIS</b></p>
|
|
|
|
<dir>
|
|
<li>#include <sys/vfs.h><p>int <b>statfs</b>(char *<i>path</i>,
|
|
struct statfs *<i>buf</i>)</p>
|
|
<p>int <b>fstatfs</b>(int <i>fd</i>, struct statfs *<i>buf</i>)</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>DESCRIPTION</b></p>
|
|
|
|
<dir>
|
|
<li><b>statfs</b> returns information about a mounted file
|
|
system. <i>path</i> is the path name of any file within
|
|
the mounted filesystem. <i>Buf</i> is a pointer to a
|
|
statfs structure defined as follows:<p><font size="2"
|
|
face="Courier New">typedef struct {</font></p>
|
|
<p><font size="2" face="Courier New">long val[2];</font></p>
|
|
<p><font size="2" face="Courier New">} fsid_t;</font></p>
|
|
<p><font size="2" face="Courier New">struct statfs {</font></p>
|
|
<p><font size="2" face="Courier New">long f_type; /* type
|
|
of info, zero for now */</font></p>
|
|
<p><font size="2" face="Courier New">long f_bsize; /*
|
|
fundamental file system block size */</font></p>
|
|
<p><font size="2" face="Courier New">long f_blocks; /*
|
|
total blocks in file system */</font></p>
|
|
<p><font size="2" face="Courier New">long f_bfree; /*
|
|
free blocks */</font></p>
|
|
<p><font size="2" face="Courier New">long f_bavail; /*
|
|
free blocks available to non-superuser */</font></p>
|
|
<p><font size="2" face="Courier New">long f_files; /*
|
|
total file nodes in file system */</font></p>
|
|
<p><font size="2" face="Courier New">long f_ffree; /*
|
|
free file nodes in fs */</font></p>
|
|
<p><font size="2" face="Courier New">fsid_t f_fsid; /*
|
|
file system id */</font></p>
|
|
<p><font size="2" face="Courier New">long f_spare[7]; /*
|
|
spare for later */</font></p>
|
|
<p><font size="2" face="Courier New">};</font></p>
|
|
<p>Fields that are undefined for a particular file system
|
|
are set to -1. <b>fstatfs</b> returns the same
|
|
information about an open file referenced by descriptor <i>fd</i>.</p>
|
|
</li>
|
|
</dir>
|
|
|
|
<p><b>RETURN VALUE</b></p>
|
|
|
|
<dir>
|
|
<li>Upon successful completion, a value of 0 is returned.
|
|
Otherwise, -1 is returned and the global variable <b>errno</b>
|
|
is set to indicate the error.</li>
|
|
</dir>
|
|
|
|
<p><b>ERRORS</b></p>
|
|
|
|
<dir>
|
|
<li><b>statfs</b> fails if one or more of the following are
|
|
true:<p><font face="Courier New">ENOTDIR</font> A
|
|
component of the path prefix of <i>path</i> is not a
|
|
directory.</p>
|
|
<p><font face="Courier New">EINVAL</font> <i>path</i>
|
|
contains a character with the high-order bit set.</p>
|
|
<p><font face="Courier New">ENAMETOOLONG</font> The
|
|
length of a component of <i>path</i> exceeds 255
|
|
characters, or the length of path exceeds 1023
|
|
characters.</p>
|
|
<p><font face="Courier New">ENOENT</font> The file
|
|
referred to by <i>path</i> does not exist.</p>
|
|
<p><font face="Courier New">EACCES</font> Search
|
|
permission is denied for a component of the path prefix
|
|
of path.</p>
|
|
<p><font face="Courier New">EIO</font> An I/O error
|
|
occurred while reading from or writing to the file
|
|
system.</p>
|
|
<p><b>fstatfs</b> fails if one or both of the following
|
|
are true:</p>
|
|
<p><font face="Courier New">EBADF</font> <i>fd</i> is not
|
|
a valid open file descriptor.</p>
|
|
<p><font face="Courier New">EIO</font> An I/O error
|
|
occurred while reading from or writing to the file system</p>
|
|
</li>
|
|
</dir>
|
|
</body>
|
|
</html>
|