NAME
intro - introduction to commands and application programs

DESCRIPTION
This section describes, in alphabetical order, commands available for GNO. Certain distinctions of purpose are made in the headings. For example, BUILT-IN UTILITIES are those commands which are part of the GNO shell and not contained in stand-alone files.

Manual Page Command Syntax
Unless otherwise noted, commands described in the SYNOPSIS  section of a manual page accept options and other arguments according to the following syntax and should be interpreted as explained below:

name  [- option ...] [ cmdarg ...]

where:

[]	Surround an option or cmdarg that is not required.

...	Indicates multiple occurrences of the option or cmdarg.

name 	The name of an executable file.

option 
	(Almost always preceded by a "-".)
	noargletter ... or,
	argletter optarg [,...]

noargletter 
	A single letter representing an option without an option-argument. Note that more than one noargletter option can be grouped after one "-".

argletter
	A single letter representing an option requiring an option-argument.

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.

cmdarg
 	Path name (or other command argument)  not  beginning with a "-", or "-" by itself indicating the standard input.

SEE ALSO
GNO Shell User's Manual
NAME
binprint - dump binary files in ascii/hex format

SYNOPSIS
binprint [-c columns] [filename]

DESCRIPTION
binprint takes binary data and formats it as a sequence of ascii data and hex values that represent the binary data. The format of the output is very similar to that produced by the IIGS Monitor and the NiftyList utility.

Two columns of output are produced. The first column is the hex representation of the data.  The second column is the ascii representation of the data. If the particular byte being printed is a non-printable ASCII character, it is printed as a '.'.

If the -c option is specified, the number following it is used to determine the number of columns (of bytes) per line. The default is 16.

If the filename is not specified, input is taken from standard input.

BUGS
binprint is slow.

AUTHOR
binprint was written by Derek Taubert for GNO/ME.

NAME
cal - display a calendar

SYNOPSIS
cal [ [  month  ]  year  ]

DESCRIPTION
cal displays a calendar for the specified year. If a month is also specified, a calendar for that  month  only is displayed. If neither is  specified, a calendar for the present month is printed.

year can be between 1 and 9999. Be aware that  `cal  78' refers to the early Christian era, not the 20th century. Also, the year is always considered to start in January, even though this is historically naive.

month  is a number between 1 and 12.

The calendar produced is that for England and her colonies.

Try September 1752.

NAME
cat - concatenate and print files

SYNOPSIS
cat [ -benstuv ] [ file ...]

DESCRIPTION
The cat utility reads files sequentially, writing them to the standard output.  The file operands are processed in command line order.  A single dash represents standard input.

The options are as follows:

-b	Implies the -n option but doesn't number blank lines.
-e	Implies the -v option, and displays a dollar sign ($) at the end of each line as well.
-n	Number the output lines, starting at 1.
-s	Squeeze multiple adjacent empty lines, causing the output to be single spaced.
-t	Implies the -v option, and displays tab characters as [^I] as well.
-u	The -u option guarantees that the output is unbuffered.
-v	Displays non-printing characters so they are visible. Control characters print line [^X] for control-X; the delete character (octal 0177) prints as [^?] Non-ascii characters (with the high bit set) are printed as [M-] (for meta) followed by the character for the low 7 bits.

The cat utility exits 0 on success, and >0 if an error occurs.

BUGS
Because of the shell language mechanism used to perform output redirection, the command "cat file1 file 2 > file1" will cause the original data in file1 to be destroyed!  Use "cat file2 >> file1" instead.

SEE ALSO
head(1), more(1), tail(1), Rob Pike "UNIX Style, or cat -v Considered Harmful", "USENIX Summer Conference Proceedings" (1983)

HISTORY
A cat command appeared in Version 6 AT&T UNIX.

NAME
center - Center text on terminal

SYNOPSIS
center [columns] [file]

DESCRIPTION
Center is used to center lines of text either fed from stdin, or from the specified file.

One may pipe input in to it from the command line, or launch it by itself.

The commands are as follows:

columns	How many columns should be considered when centering the text.
Defaults to 80 columns.

file		Specifies the file to open for centering. Defaults to stdin.

FILES
center

AUTHOR
Written by Marek Pawlowski.  Source code in Public Domain. Contact author for redistribution rights, or inclusion in a software package.  Munge at will.  Credit to Marek Pawlowski must be retained in modified source code.  Preview of modifications appreciated.  Contact Marek Pawlowski at marekp@pnet91.cts.com, marekp@cerf.net.

NAME
chmod - Modify file permission flags.

SYNOPSIS
chmod [vV] [octnum]|[+-=][rwdnbi] file...

DESCRIPTION
chmod is a program which modifies the permission flags of a series of files.  It will modify the read, write, destroy, rename, backup, and invisible flags of the files selected.

OPTIONS
-v 	verbose.  Provides debugging information.
-V 	version.  Prints out the version number.

USAGE
-	remove a permission flag.
+	add a permission flag.
=	add permission flag, and clear all other flags.

PERMISSIONS
r	read permssion.
w	write permission.
d	destroy permission.
n	rename permission.
b	backup needed flag.
i	invisible flag.

EXAMPLES
`Lock' a file:   % chmod -wdn foo 
`Unlock' a file: % chmod +wdn foo

BUGS
Currently octal mode is only guarenteed to work with the ProDOS filesystem, as the chmod() call supplied with Orca/C doesn't seem to work well with other FSTs.  Many of the standard Unix permission flags are not implemented, as the ProDOS filesystem does not support these permissions.  Among unsupported permissions are seperate sets of flags for user, group, and world.  As well, the -x  flag is not supported - if you wish to create an executable shell script, use chtyp instead.

SEE ALSO
ls(1), chtyp(1)

AUTHOR
James Brookes
bb252@cleveland.freenet.edu
jamesb@cscihp.ecst.csuchico.edu

NAME
chtyp - change file and aux types

SYNOPSIS
chtyp { [-t filetype] [-a auxtype] } | { -l lang } file...

DESCRIPTION
chtyp is used to change the file types and aux types of the specified file(s).

type is one of:
a decimal number [66]
a hexidecimal number preceeded by a $ [$42]
an official Apple mnemonic [FTD]

and auxtype is either:
a decimal number [64222]
a hexidecimal number preceeded by a $ [$FADE]

lang is one of:
	CC	ORCA/C
	ASM65816	ORCA/M or APW Assembler
	IBASIC	ORCA/Integer Basic
	LINK	ZapLink
	APWC	APW C
	PASCAL	ORCA/Pascal
	REZ	Apple Resource Tool
	EXEC	Shell Script file
	TMLPASCAL	TML Pascal 

If the -l is used, the -t and -a options cannot be used.

ERRORS
If chtyp is interrupted with a signal (SIGINT, SIGTERM, etc.) the program aborts with a message telling what signal caused the termination.

If some other error occurs, chtyp aborts with an error message.

BUGS
Note that when giving hexadecimal arguments to chtyp, you must quote any '$' characters with a \. For example,
chtyp -t \$50 -a \$8002 teach.file

	Additional language stamps can only be added by modifying the source code.

AUTHOR
Original version by Greg Thompson.

NAME
cmp - perform a byte-by-byte comparison of two files

SYNOPSIS
cmp [ -ls ] filename1  filename2  [ skip1 ] [ skip2 ]

DESCRIPTION
cmp compares filename1 and filename2  . If filename1  is `-', the standard input is used.  With no options, cmp makes no comment if the files are the same; if they differ, it reports the byte and line number at which the difference occurred, or, that one file is an initial subsequence of the other. 

skip1 and skip2 are initial byte offsets into filename1 and filename2 respectively, and may be either octal or decimal; a leading 0 denotes octal.

OPTIONS
-l	Print the byte number (in decimal) and the differing bytes (in octal) for all differences between the two files.
-s	Silent. Print nothing for differing files; set exit codes only.

SEE ALSO
diff(1)

DIAGNOSTICS
Exit code 0 is returned for identical files, 1 for different files, and 2 for an inaccessible or missing argument, or a system error.

NAME 
compress, uncompress, zcat - compress and expand data

SYNOPSIS
compress [-cCdDf?hkKvV][-b maxbits][-Iinpath][-Ooutpath][filenames...]
uncompress [-fCcvVkK?h][-Iinpath][-Ooutpath][filenames...]
zcat [-CvV?h][-Iinpath][-Ooutpath][filenames...]

     -V		print Version
     -d 		decompress input (default is compress)
     -v 		verbose
     -f		force overwrite of output file (default = off)
     -n 		no header: useful to uncompress old files
     -c 		write all output to stdout (default = off)
     -C		generate output compatible with compress 2.0
     -k 		%s input file (default = keep)
     -K		%s output file on error (default = kill)
     -b maxbits		default = 16  bits
     -I pathname		infile path  = none
     -O pathname		outfile path = none
     -? -h		help, print full usage message

DESCRIPTION
Compress reduces the size of the named files using adaptive Lempel-Ziv coding. Whenever possible, each file is replaced by one with the extension .Z, while keeping the same ownership modes, access and modification times. If no files are specified, the standard input is compressed to the standard output.Compressed files can be restored to their original form using uncompress or zcat.

The -f option will force compression of name. This is useful for compressing an entire directory, even if some of the files do not actually shrink. If -f is not given and compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten.

The -c option makes compress/uncompress write to the standard output; no files are changed.  The nondestructive behavior of zcat is identical to that of uncompress -c.

Compress uses the modified Lempel-Ziv algorithm popularized in "A Technique for High Performance Data Compression", Terry A. Welch, "IEEE Computer," vol. 17, no. 6 (June 1984), pp. 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the -b flag is reached (default 16). Bits must be between 9 and 16.  The default can be changed in the source to allow compress to be run on a smaller machine.

After the bits limit is attained, compress periodically checks the compression ratio.  If it is increasing, compress continues to use the existing code dictionary.  However, if the compression ratio decreases, compress discards the table of substrings and rebuilds it from scratch.  This allows the algorithm to adapt to the next "block" of the file.

Note that the -b flag is omitted for uncompress, since the bits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted.

The amount of compression obtained depends on the size of the input, the number of bits per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60%. Compression is generally much faster compressing, but the output is not as small as freeze.

Under the -v option, a message is printed yielding the percentage of reduction for each file compressed.

If the -V option is specified, the current version and compile options are printed on stderr.

RETURN VALUE
Exit status is normally 0; if the last file is larger after (attempted) compression, the status is 2; if an error occurs, exit status is 1.

SEE ALSO
freeze(1)

DIAGNOSTICS
Usage: compress [\-dfvcV] [\-b maxbits] [file ...]
Invalid options were specified on the command line.
Missing maxbits
Maxbits must follow -b.
file : not in compressed format
The file specified to uncompress has not been compressed.
file : compressed with bits, can only handle yy bits
File was compressed by a program that could deal with more bits than the compress code on this machine. Recompress the file with smaller bits.
file : already has .Z suffix -- no change
The file is assumed to be already compressed. Rename the file and try again.
file : filename too long to tack on .Z
The file cannot be compressed because its name is longer than 12 characters.  Rename and try again. This message does not occur on BSD systems. 
file already exists; do you wish to overwrite (y or n)?
Respond "y" if you want the output file to be replaced; "n" if not.
Compression: "xx.xx%"
Percentage of the input saved by compression. (Relevant only for -v.)
-- not a regular file: unchanged
When the input file is not a regular file,(e.g. a directory), it is left unaltered.
-- file unchanged
No savings is achieved by compression.  The input remains virgin.

BUGS
Although compressed files are compatible between machines with large memory, -b 12 should be used for file transfer to architectures with a small process data space (64KB or less, as exhibited by the DEC PDP series, the Intel 80286, etc.)

NAME
conv - convert file formats

SYNOPSIS
conv -convspec file1 ...

DESCRIPTION
conv converts files between various formats.  convspec is a specification detailing the type of file1 and the type to convert it to. 

-crlf	convert line terminators from CR (Apple) to LF (Unix).

-lfcr	convert line terminators from LF (Unix) to CR (Apple).

-detab spacing	translate tabs to spaces, using tabs every spacing characters.  A smart algorithm is used which only inserts enough spaces to move to the next tab stop.  spacing is an integer less than 20.

-0001	converts all 0x00 bytes to 0x01 for using Macintosh sound files on the IIgs.

NOTES
conv is very quick on all the conversions except -detab (speed approaches 30K/sec). conv works under the Orca shell also, and supports the Orca method of wildcards.  Look at the code to see how nasty this makes programs.

SEE ALSO
cat(1), more(1), tr(1)

AUTHOR
conv was written by Greg Thompson for GNO/ME.

NAME
du - Display disk usage statistics

SYNOPSIS
du [ -aksx ] pathname ...

DESCRIPTION
The du utility displays the block usage of files in the current directory or for the entire tree of a given pathname.

The options are as follows:

-a	Generate an entry for each file.
-k	By default, du displays the number of blocks as returned by the stat(2) system call, i.e. 512-byte blocks. If the -k flag is specified, the number displayed is the number of 1024-byte blocks with partial blocks rounded up.
-s	Generate only the grand total.  If neither -a or -s are specified, an entry is generated for each directory only.
-x	Don't traverse any mount points.

Files having multiple hard links are counted (and displayed) a single time per du execution.

SEE ALSO
df(1)

BUGS
The Apple IIGS does not have the concept of mount points, and thus the -x option is useless.

HISTORY
A du command appeared in Version 6 AT&T Unix.

NAME
eps - display extended process status information.

SYNOPSIS
eps [-anlw] [-t tty] [-u user]

DESCRIPTION
eps is an extended ps command which displays more information than the gsh builtin ps.

USAGE
-a	Show all processes; normally eps limits the processes displayed to those that are owned by the current user.

-n	Show username instead of userID, which is default.
-l	Long list.  This includes PPID (parent's PID), MMID (Memory Manager ID) and a longer time field.
-w	Wider list.  A single w results in a 132 column wide listing, and two results in the whole command line being displayed.  Normally the command line will be truncated to either 80 (default) or 132 (-w) columns.
-t  tty	Display only those processes that are owned by tty.
-u user	Display only those processes that are owned by user.

SEE ALSO
GNO Shell Reference Manual, parent(1)

AUTHOR
James Brookes
bb252@cleveland.freenet.edu
jamesb@cscihp.ecst.csuchico.edu

NAME
fold -  fold long lines for finite width output device

SYNOPSIS
fold [ -w width ] 

DESCRIPTION
Fold is a filter which folds the contents of the specified files, or the standard input if no files are specified, breaking the lines to have maximum of 80 characters.

The options are as follows:

-w width
Specifies a line width to use instead of the default 80 characters.Width should be a multiple of 8 if tabs are present, or the tabs should be expanded using conv(1) before using fold .

SEE ALSO
conv(1)

BUGS
If underlining is present it may be messed up by folding.

NAME
getvers,setvers - manipulate rVersion resources in executable files

SYNOPSIS
getvers filename
setvers file   ' string1 ~ string2 ' [ country ] vmajrev.minrev.bugrev

DESCRIPTION
getvers accepts as input the name of an executable file, and prints the version information stored in the rVersion resource of the file. If no rVersion resource is present it will abort with the error `This file has no rVersion resource'.

To add information to the rVersion resource, setvers is used. The rVersion format allows for two stirngs of up to 255 characters, although it is suggested that for this use you keep each field shorter than 80 characters.

string1 is separated from string2 by a ~ (tilde) character, and both strings should be enclosed in single quotes. string1 is required to be the name of the program.  Any `_' character in string2 will be interpreted as a carriage return.  When using GNO, make sure to quote the single quotes and the tilde with backslashes.  

The optional field country (no spaces allowed) allows you to set the country field of the rVersion resource.  The last parameter is the current revision number of the program in the format majrev . minrev . bugrev, where
majrev is a single or double digit number from 00 to 99, and minrev and bugrev are single digit numbers from zero to nine.

COUNTRIES
Valid Countries/Regions (case IS sensitive)
Arabia	Iceland
Australia	Israel
Belgium/Luxembourg	Italy
Bosnia/Herzegovena	Japan
Britian	Korea
China	Malta
Cyprus	Netherlands
Denmark	Norway
Finland	Portugal
France	Spain
FrenchCanadian	Sweden
FrenchSwiss	Taiwan
GermanSwiss	Thailand
Germany	Turkey
Greece	UnitedStates

EXAMPLES
Set the version of program `chmod' to read:

chmod v01.0.0
James Brookes
jamesb@cscihp.ecst.csuchico.edu
Country: United States

in Orca:

# setvers chmod 'chmod~James Brookes_jamesb@cscihp.ecst.csuchico.edu' v01.0.0

in GNO:

% setvers chmod \'chmod\\~James Brookes_jamesb@cscihp.ecst.csuchico.edu\' v01.0.0

CAVEATS
If an rVersion resource already exists, it will be overwritten and replaced with the new one.  Other resources will be unaffected.

BUGS
Little crawly things, also known as insects.

AUTHOR
Ian Schmidt - Two Meg Software  (irsman@iastate.edu)

NAME
grep, egrep, fgrep - search a file for a string or regular expression

SYNOPSIS
grep [ -bchilnsvw ] [ -e expression ] [ filename ... ]
egrep [ -bchilnsv ] [ -e expression ] [ -f filename ] [  expression  ] [  filename ... ] 
fgrep [ -bchilnsvx ] [ -e  string  ] [ -f filename ] [ string ] [ filename ... ]

DESCRIPTION
Commands of the grep family search the input filenames  (the standard input default) for lines matching a pattern.  Normally, each line found is copied to the standard  output.  grep patterns are limited regular expresions in the style of ed(1).   egrep patterns are full  regular expressions including alternation. fgrep patterns are fixed strings - no regular expression metacharacters are supported, and as a result fgrep is generally an order of magnitude faster than the other versions of grep.

Take care when using the characters `$', `*', [,  `^', `|', `(', `)', and `\' in the expression, as these characters are also meaningful to the shell.  It is safest to enclose the entire expression argument in single quotes `...'

When any of the grep utilities is applied to more than one input file, the name of the file is displayed preceding each line which  matches the  pattern.   The  filename is not displayed when processing a single file, so if you actually want the filename to appear, use .null as a second  file in the list.

OPTIONS
-b	Precede each line by the block number on which  it  was found.  This is sometimes useful in locating disk block numbers by context.

-c	Display a count of matching lines rather than displaying the lines which match.

-h	Do not display filenames.

-i	Ignore the case of letters in making comparisons - that is, upper and lower case are considered identical.

-l	List only the names of files with matching lines (once) separated by NEWLINE characters.

-n	Precede each line by its relative line number in the file.

-s	Work silently, that is, display nothing except error messages.   This is useful for checking the error status.

-v	Invert the search to only display lines that  do not  match.

-w	Search for the expression as a word as if surrounded by \< and \>.  This applies to grep only.

-x	Display only those lines which match exactly - that is, only lines which match in their entirety.  This applies to fgrep only.

-e expression 
	Same as a simple expression argument, but useful when the expression begins with a `-'.

-e  string
	For fgrep the argument is a literal character string .

-f  filename 
	Take the regular expression (egrep) or a list of strings separated by NEWLINE (fgrep) from filename .

REGULAR EXPRESSIONS
The following one-character regular expressions match a single character:

c	An ordinary character ( not  one of the  special  characters   discussed  below)  is  a  one-character  regular expression that matches that character.

\ c	A backslash (\) followed by any special character is  a one-character  regular expression that matches the special character itself.  The special characters are:

•	`.', `*', `[',  and  `\'  (period,  asterisk, left  square  bracket, and backslash, respectively), which  are  always  special,  except  when they appear within square brackets ([]).

•	`^' (caret or circumflex), which  is  special at the  beginning  of an  entire  regular expression, or when it immediately follows the left of a pair of square brackets ([]).

•	$ (currency symbol), which is special at  the end of an entire regular expression.

A backslash followed by one of `<', `>', `(', `)',  `{',  or `}',  represents a special operator in the regular expression; see below.

.	A `.' (period) is a  one-character  regular  expression that matches any character except NEWLINE.

[ string ]
	A non-empty string of characters enclosed in square brackets is a one-character regular expression that matches any one character in that string.  If, however, the first character of the string is a `^' (a circumflex or caret), the one-character  regular  expression matches any character except NEWLINE and the remaining characters in the string.  The `^' has this special meaning only if it occurs first in the string.  The `-' (minus) may be used to indicate a range of consecutive ASCII characters;  for example, [0-9] is equivalent to [0123456789].  The `-' loses this special meaning if it occurs  first (after an initial `^', if any) or last in the string.  The `]' (right square  bracket) does not terminate such a string when it is the first character within it (after an initial  `^',  if any); that is, []a-f]  matches either `]' (a right square bracket ) or one of the letters a through  f  inclusive.  The four characters `.', `*', `[', and `\' stand for themselves within such a string of characters.

The following rules may be used to construct regular expressions:

*	A one-character regular expression followed by `*' (an asterisk) is a regular expression that matches  zero or more occurrences of the one-character regular expression.   If there is  any choice, the longest leftmost string that permits a match is chosen.

\(and\)
	A regular expression enclosed between the character  sequences \( and \) matches whatever the unadorned regular expression matches.  This applies only to grep.

\ n	The expression \ n  matches the same string of characters as was matched by an expression enclosed between \( and \)  earlier  in the same regular expression.  Here  n  is a  digit;  the  sub-expression specified is that beginning with the  n th occurrence of \( counting from  the  left.  For  example, the expression ^\(.*\)\1$ matches a line consisting of two repeated appearances of the same string.

Concatenation
The concatenation of regular expressions is a regular expression that matches the concatenation of the strings matched by each component of the regular expression.

\<	The sequence \< in a regular expression constrains the one-character regular expression immediately following it only to match something at the beginning of a word; that  is, either at the beginning of a line, or just before a letter, digit, or underline and after a character not one of these.

\>	The sequence \> in a regular expression constrains  the one-character  regular expression immediately following it only to match something at the end of a  word;  that is, either at the end of a line, or just before a character which is neither a letter, digit, nor underline.

\{ m \}
\{ m ,\}
\{ m , n \}
	A regular expression followed by \{ m \},  \{ m , \ },  or \{ m , n \}  matches a range of occurrences of the regular expression.  The values of  m  and  n  must be non-negative integers   less  than 256;  \{ m \}  matches exactly  m  occurrences; \{ m ,\} matches at least  m  occurrences; \{ m , n \} matches  any  number  of occurrences  between  m  and n  inclusive.  Whenever a choice exists, the regular expression matches as many occurrences as possible.

^	A circumflex or caret (^) at the beginning of an entire regular expression constrains that regular expression to match an  initial segment of a line.

$	A currency symbol ($) at the end of an entire regular expression constrains that regular expression to match a final segment of a line.

The construction

example% ^ entire regular expression  $

constrains the entire regular expression to match the entire line.

egrep accepts regular expressions of the same sort grep does, except for \(, \), \ n, \<, \>, \{, and \}, with the addition of:

*	A  regular expression (not just a one-character regular expression) followed by `*' (an asterisk) is a regular  expression that matches zero or more occurrences of the one-character regular expression.   If  there is any  choice, the longest leftmost string that permits a match is chosen.

+	A regular expression followed by `+' (a  plus sign) is a regular expression that matches one or more occurrences of the  one-character regular expression.  If there is any choice, the longest leftmost string that permits a match is chosen.

?	A regular expression followed by `?' (a question  mark) is a regular expression that matches zero or one occurrences of the one-character regular expression.  If there is any choice, the longest leftmost string that permits a match is chosen.

|	Alternation:  two regular expressions separated by `|' or NEWLINE match either a match for the first or a match for the second.

()	A regular expression enclosed in parentheses matches a match for the regular expression.

The order of precedence of operators at the same parenthesis level is `[ ]' (character classes), then `*' `+' `?' (closures),then  concatenation, then `|' (alternation) and NEWLINE.

EXAMPLES

Search a file for a fixed string using fgrep:

	example% fgrep intro /usr/share/man/man3/*.3*

Look for character classes using grep:

	example% grep '[1-8]([CJMSNX])' /usr/share/man/man1/*.1

Look for alternative patterns using egrep:

	example% egrep '(Sally|Fred) (Smith|Jones|Parker)' telephone.list

To get the filename displayed when only processing a single file, use .null as the second file in the list:

	example% grep 'Sally Parker' telephone.list /dev/null

FILES
	.null

SEE ALSO
	awk(1), gsh(1), vi(1), sed(1)

BUGS
	Lines are limited to 1024 characters by grep; longer lines are truncated.

The combination of -l and -v options does not produce a list of files in which a regular expression is not found.  To get such a list, use the C shell construct (Note: this is NOT the same as gsh, which does not support such programming).

	foreach  filename  (*)
		if (`grep " re " $ filename  | wc -l` == 0) echo $ filename 
	end

Ideally there should be only one grep.

DIAGNOSTICS
Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files.

NAME
head - give first few lines

SYNOPSIS
head [-count] [file ...]

DESCRIPTION
This filter gives the first count lines of each of the specified files, or of the standard input.  If count is omitted it defaults to 10.

SEE ALSO
tail(1)

HISTORY
head appeared in 3 BSD.

NAME
ls - list contents of directory

SYNOPSIS
ls [ -acdfilqrstu1ACLFR ] name ...

DESCRIPTION
For each directory argument,  ls  lists the contents of the directory; for each file argument,  ls  repeats its name and any other information requested.  By default, the output is sorted alphabetically.  When no argument is given, the current directory is listed.  When several arguments are given, the arguments are first sorted appropriately, but  file arguments are processed before directories and their contents.

There are a large number of options:

-l	List in long format, giving mode, number of links,owner, size in bytes, and time of last modification for each file.  If the file is a special file the size field will instead contain the major and minor device numbers.  If the file is a symbolic link the pathname of the linked-to file is printed preceded by ``->''.

-t	Sort by time modified (latest first) instead of by name.

-a	List all entries; in the absence of this option, entries whose names begin with a period (.) or whose GS/OS 'invisible' flag is set are  not  listed.

-A	List all entries except for the current directory (.)  and the parent directory (..).

-s	Give size in kilobytes of each file.

-d	If argument is a directory, list only its name; often used with -l to get the status of a directory.

-L	If argument is a symbolic link, list the file or directory the link references rather than the link itself.  Note that if the link references a directory the link is always followed, unless the -l option is used.

-r	Reverse the order of sort to get reverse alphabetic or oldest first as appropriate.

-u	Use time of last access instead of last modification for sorting (with the -t option) and/or printing (with the -l option).

-c	Use time of file creation for sorting or printing.

-i	For each file, print the i-number in the first column of the report.

-f	Force each argument to be interpreted as a directory and list the name found in each slot. This option turns off -l, -t, -s, and -r, and turns on -a; the order is the order in which entries appear in the directory.

-F	Cause directories to be marked with a trailing `/', sockets with a trailing `=', executable files with a trailing `*', and symbolic links to files with a trailing `@'.  Symbolic links to directories are marked with a trailing `/', unless the -l option is also used.

-R	recursively list subdirectories encountered.

-1	force one entry per line output format; this is the default when output is not to a terminal.

-C	force multi-column output; this is the default when output is to a terminal.

-q	force printing of non-graphic characters in file names as the character `?'; this is the default when output is to a terminal.

-n	Causes ls to not sort files; this is useful when organizing libraries in alphabetical order for ORCA languages.

The mode printed under the -l option contains 11 characters which are interpreted as follows: the first character is

e	if the entry has a resource fork,
d	if the entry is a directory;
b	if the entry is a block-type special file;
c	if the entry is a character-type special file;
l	if the entry is a symbolic link;
s	if the entry is a socket, or
-	if the entry is a plain file.

The next 9 characters are interpreted as three sets of three bits each.  The first set refers to owner permissions; the next refers to permissions to others in the same user-group; and the last to all others.  Within each set the three characters indicate permission respectively to read, to write, or to execute the file as a program.  For a directory, `execute' permission is interpreted to mean permission to search the directory.  The permissions are indicated as follows:

i	if the file is invisible
d	if the file can be deleted
r	if the file is readable;
w	if the file is writable;
x	if the file is executable;
-	if the indicated permission is not granted.

The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the user-execute permission character is given as s if the file has the set-user-id bit set.

When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is printed.

BUGS
The output device is assumed to be 80 columns wide.
GNO and GS/OS do not currently support links, user/group permissions, the concept of 'i-numbers', or 'special' files; thus, ls options that deal with these are ignored.

NAME
lseg - list segments in an OMF file

SYNOPSIS
lseg file

DESCRIPTION
lseg lists the segments of an OMF executable file.  While it can list the segments in an intermediate object file, the information isn't as useful.

lseg is intended for discovering the location of stack segments in existing applications (for editing to smaller sizes), as an aid in determining how to segment large C files whose segments exceed the bank size, and for deciding which segments to recombine after excessive segmentation.

AUTHOR
Jawaid Bazyar for GNO/ME.

BUGS
Doesn't detect non-OMF files, and thus can get very confused if you do "lseg *" and one of the files chosen isn't an OMF file.  Usually the only way to terminate is to interrupt the program with ^C.

NAME
make - build a program according to a program definition file

SYNOPSIS
make [-d] [-p] [-s] inputFile

DESCRIPTION
make is a program maintenance utility that aids in creating programs from multiple source files.

inputFile is the name of the Program Description File. If absent, make defaults to using 'makefile' as the PDF. make's options are as follows:

-d   Display the modification date and time as each file is checked. 
-p   Operate in programmer/debug mode. 
-s   Operate in silent mode.

The logical definition of each of the PDF parameters follows:

# Comments begin with a pound sign "#". 
# 
TargetFile: DependentFile1 \ #
DependentFile2 DependentFilen 
  ShellCommand1 
  ShellCommand2 
	. 
	. 
  ShellCommandn

MAKE PARAMETERS
Comments can be placed anywhere in the PDF file.  If a pound sign is in column one, the entire line is treated as a comment.  Anything following the pound is ignored by make. Comments may also be placed on parameter lines containing Target/Dependent file parameters.

The TargetFile parameter must start in column one and ends with a colon ":".  It can be a full path name, partial path name or file in the current directory.  This file is usually an object type file created by a compiler.  Dependent file parameter(s) follow the semicolon and are separated by a space, a comma or both.  Dependent file parameters are usually CC, PAS, ASM or some type of included SRC file.  Essentially, TargetFile is the result of compiling the dependent source files.

make obtains the modfication date and time of the Target file and then compares it to each of the dependent file(s) moving left to right.  If one of the dependent files has a date and time later than the Target file, the subsequent ShellCommands are executed.  Target/Dependent parameters may be continued by placing a reverse slash "\" on the line following a dependent file parameter.  make will interpret the next line as dependent file parameters which may also be continued and so on.  There should not be any blank lines between the continued line and next line.

ShellCommands must contain a space in column one to differentiate them from Target/Dependent file parameters.  If make determines that a Target file needs to be recreated, the ShellCommands following the Target/Dependent file parameters are passed, as is, to the shell interpreter.  The commands must be valid shell commands.  ShellCommands are executed until a blank line is encountered or an error occurs during the execution of the last command.  If an error occurs, make terminates without reading the remaining PDF parameters.  If a blank line is read, make returns to Target/Dependent search mode.

MAKE Example

# 
#  File: Example.Make - A MAKE example PDF #

Menu.Root:  Menu.CC # Contains menu related routines 
 compile menu.cc keep=menu

Window.Root: Window.CC # Contains window handling routines 
 compile window.cc keep=window

Misc.Root: Misc.CC Misc.h # Contains miscellaneous program routines 
 compile misc.cc keep=misc

Main.Root: Main.CC Include/Main.h Include/Misc.h # Main program 
 compile main.cc keep=main

MyProg: Menu.Root Window.Root Misc.Root \ # re-link required? 
	Main.Root				# check all dependent files 
 link main misc menu window keep=myprog	# Shell comment 
 chtyp -t s16 myprog			# change type to S16

# End of PDF

The example PDF shows a program that is made up of 4 source files.  The Main and Misc routines are also dependent on include files containing information that if changed would force a re-compile of that module.

One thing to keep in mind is the order of Target/Dependent parameters can be important.  make examines the PDF from the top down.  If a file is modified due to a command later in the PDF, make will not return to a previous Target/Dependent parameter in which that file was a dependent file.

AUTHOR
Original make util written by Larry Agle for ORCA; modifications made to make it look more like UNIX make, and misc. Bug fixes by Jawaid Bazyar.

NAME
makemake - scan C source files for dependencies and create a makefile

SYNOPSIS
makemake source.c 

DESCRIPTION
makemake takes the C source file(s) as input, and scans them for dependencies (#includes). It does not count standard headers (#includes with the filename surrounded by < >).

The dependency information for all the source files specified is then written to a file 'makefile' in the current directory.

makemake does not create link scripts nor does it put an executable dependendcy into the file, as these require link information not available from the makemake command line.

AUTHOR
Jawaid Bazyar for GNO/ME's 'make' utility. He got tired of writing them by hand.

BUGS
makemake does not properly handle recursive or multiple includes of the same file. If the same file is included more than once, makemake will list it that many times in the output makefile. While multiple includes don't hurt anything, it can take more time to process the makefile. Recursive includes will, of course, hang makemake.

NAME
man - online manual system (Version 1.6)

SYNOPSIS
man [ section ] manpagename

DESCRIPTION
man is the access point to the online manual system.  man works as a shell that calls an appropriate text formatter to format a manual page.  There are currently three text formatters available for the GNO/ME system.

nroff	Unix standard typesetting package
aroff	formats AppleWorks GS(tm) documents
cat	used to display preformatted documents

If the option section argument is specified, man looks specifically in that section of the manual for the manpage.  This is needed in situations where there are manpages with the same name in different sections (for example, sleep(1) and sleep(3).

ENVIRONMENT
man recognizes the following variables from the shell.

USRMAN
	This variable is required . It points to the manual system root directory.
PAGER
	man uses more as the default pager.  If you wish to use a different pager, less perhaps, then you must set this variable to point to that pager.

Compressed Manual Pages and Links
If man finds a file in the manual that ends in a '.l' suffix, it takes the contents of that file as a 'link' to the actual manpage.  This is useful for manpages that describe multiple commands, and prevents having multiple copies of the manpage.

Manual pages may be compressed with compress or freeze, in which case the appropriate program is called to uncompress the manual file.

SEE ALSO
more(1), less(1), compress(1), freeze(1).

NAME
mkdir - Makes directories

SYNOPSIS
mkdir dirname ...

DESCRIPTION
The mkdir command creates subdirectories with the dirnames specified.  If a file with that dirname exists, an error is returned. dirname may be a full pathname, or a partial pathname, in which case the directory is created as a subdirectory of the current directory.

mkdir only creates the filename portion of the specified path.  If, for instance, you do 
mkdir /usr/local/bbs/foo
directory foo will only be created if all of /usr, local, and bbs exist.

AUTHOR
mkdir was written by James Brookes for GNO/ME.

NAME
more - text pager

SYNOPSIS
more [ file ...]

DESCRIPTION
more allows the user to view the specified file(s) screen by screen or line by line.  If no files are specified, standard input is used.

Every time more has displayed a screen of text, it displays a prompt
 - filename (xx%) - 
indicating the percentage of the file that has been viewed and its filename.  If standard input is used,
' - more - '
is used as the prompt instead.

A number of key commands are available at the prompt.

q	quit viewing the current file, and move to the next file (if any)

[RETURN]
	display the next line of the file

[ESC]	abort more, including any more files that may have been specified

[SPACE]
	display the next page of the file

AUTHOR
This version of more was written by Jawaid Bazyar and Derek Taubert.

NAME
passwd - set a user's login password

SYNOPSIS
passwd [ -? | -v ] [ username ]

DESCRIPTION
passwd changes the specified user's password.  Only root is allowed to alter passwords other than his own.  If theusername is not given, the user's own login name is assumed.  Users other than root must then enter the old password to verify permission to change the password. Finally, the user must type the desired new password twice to insure that no mistakes are made.

To cancel passwd, type CTRL-@ when asked to enter the new password. 

The -? flag causes passwd to display a brief usage message, and the -v flag causes passwd to display version information.

SEE ALSO
login(1)

FILES
/etc/passwd - contains the password information

AUTHOR
Eric Shepherd
Internet    uerics@mcl.mcl.ucsb
AOL         Sheppy

NAME
purge - deallocate purgeable memory handles

SYNOPSIS
purge [-v]

DESCRIPTION
This program purges all memory blocks marked purgable. This is very important when using the Orca compilers and shells since certain blocks get left lying around and can (and have!) caused compiler errors. By purging memory before compiles a large percentage of strange compiler errors can be eliminated. After purging, all memory possible is then freed for usage.

-v  gives a verbose listing of each handle being purged and before and after free memory statistics.

The problems mentioned above usually occur when a program has over-written one of the ORCA FastFile system's memory handles.  Purging clears these handles and forces a reload from disk.

BUGS
Purging memory when non-shell applications are running could be dangerous.

NAME
rx, rc, rb, rz - Receive Files and Commands with X/Y/ZMODEM

SYNOPSIS
rz -tv
rb -tv
rc -tv file
rx -tv file
gz file ... [-v]
rzCOMMAND

DESCRIPTION
This program uses error correcting protocols to receive files over a dial-in serial port from a variety of programs running under many operating systems.  It is invoked from a shell prompt manually, or automatically as a result of an "sz file ..." command given to the calling program.

This is a shareware program copyrighted by Omen Technology INC.

Rz (Receive ZMODEM) receives one or more files with the ZMODEM protocol.  Pathnames are supplied by the sending program, and directories are made if necessary (and possible). Normally, the "rz" command is automatically issued by the calling ZMODEM program, but defective ZMODEM implementations may require starting rz manually.

Rb receives file(s) with YMODEM, accepting either standard128 byte sectors or 1024 byte sectors (sb -k option). The user should determine when the 1024 byte block length actually improves throughput.

If True YMODEM™ (Omen Technology trademark) file information (file length, etc.) is received, the file length controls the number of bytes written to the output dataset, and the modify time and file mode (iff non zero) are set accordingly.

If True YMODEM file information is not received, slashes in the pathname are changed to underscore, and any trailing period in the pathname is eliminated. This conversion is useful for files received from CP/M and other historical systems.

Rc receives a single file with XMODEM-CRC or XMODEM-1k-CRC protocol.  The user should determine when the 1024 byte block length actually improves throughput without causing problems. The user must supply the file name to both sending and receiving programs. Up to 1023 garbage characters may be added to the received file.

Rx receives a single file with XMODEM or XMODEM-1k protocol. The user should determine when the 1024 byte block length actually improves throughput without causing problems.  The user must supply the file name to both sending and receiving programs.  Up to 1023 garbage characters may be added to the received file.

Rz may be invoked as rzCOMMAND (with an optional leading - as generated by login(1)).  For each received file, rz will pipe the file to ``COMMAND filename'' where filename is the name of the transmitted file with the file contents as standard input.

Each file transfer is acknowledged when COMMAND exits with 0 status. A non zero exit status terminates transfers.

A typical use for this form is rzmail which calls rmail(1) to post mail to the user specified by the transmitted file name. For example, sending the file "caf" from a PC-DOS system to rzmail on a Unix system would result in the contents of the DOS file "caf" being mailed to user "caf".

The meanings of the available options are:

tim	Change timeout to tim tenths of seconds.
v	Verbose causes a list of file names to be appended to /tmp/rzlog .  More v's generate more detailed debugging output.

DIAGNOSTICS
Exit status is as follows: 0 for successful transfers.  1 if unrecoverable errors are detected.  2 if syntax errors or file access problems are detected.  3 if the program was terminated by a caught interrupt.

SEE ALSO
sz(1).

NOTES
ZMODEM's support of XOFF/XON flow control allows proper operation in many environments that do not support XMODEM uploads. Unfortunately, not all Unix versions support input flow control. The TTY input buffering on some systems may not adequately buffer long blocks or streaming input at high speed.  You should suspect this problem when you can't send data to the Unix system at high speeds using ZMODEM, YMODEM-1k or XMODEM-1k, but YMODEM with 128 byte blocks works properly.

If a program that does not properly implement the specified file transfer protocol causes rz to "hang" the port after a failed transfer, either wait for rz to time out or keyboard a dozen Ctrl-X characters.

Many programs claiming to support YMODEM only support XMODEM with 1k blocks, and they often don't get that quite right.

BUGS
This version of rz does not support some ZMODEM features.
The ASCII option's CR/LF to NL translation merely deletes CR's.

ZMODEM CAPABILITIES
Rz supports ZMODEM command execution (zcommand), incoming ZMODEM binary (-b), ASCII (-a), newer(-n), newer+longer(-N), protect (-p), Crash Recovery(-r), clobber (-y), match+clobber (-Y), compression(-Z), and append (-+) requests.  Other options sent by the sender are ignored. The default is protect (-p) and binary (-b).

FILES
/tmp/rzlog stores debugging output generated with -vv option

NAME
script - make typescript of a terminal session

SYNOPSIS
script [ -a ] [ filename ]

DESCRIPTION
script makes a typescript of everything printed on your terminal. The typescript is written to filename , or appended to filename if the -a option is given.  It can be sent to the line printer later with lpr(1). If no file name is given, the typescript is saved in the file typescript .

The script ends when the forked shell exits.

OPTIONS
-a	Append the script to the specified file instead of writing over it.

SEE ALSO
lpr (1), pty (4)

BUGS
script places everything  in the log file.  This is not what the naive user expects.

NAME
sleep - suspend execution for an interval

SYNOPSIS
sleep time

DESCRIPTION
Sleep suspends execution for time seconds.  It is used to execute a command after a certain amount of time as in a script:

sleep 105
command

SEE ALSO
alarm(3C), sleep(3)

BUGS
Time must be less than 2,147,483,647 seconds.

NAME
split - split a file into pieces

SYNOPSIS
split [ - number ] [ infile [ outfile ] ]

DESCRIPTION
split reads infile and writes it in number -line pieces (default 1000) onto a set of output files (as many files as necessary).  The name of the first output file is outfile with aa appended, the second file is outfileab , and so on lexicographically.

If no outfile is given, x is used as default (output files will be called xaa , xab , etc.).

If no infile is given, or if `-' is given in its stead, then the standard input file is used.

OPTIONS
- number	Number of lines in each piece.

NAME
stty - set and view terminal options and parameters

SYNOPSIS
stty [ option ... ] [ charoption c ... ]

DESCRIPTION
If no options are specified, stty prints out all the current terminal option settings.  options represent boolean flags in the terminal parameters, and are as follows:

raw	turns on RAW mode (no character or line processing)
-raw	turns off RAW mode
ehco	if in CBREAK or COOKED mode, echoes input characters
-echo	echo mode off
cbreak	turns on CBREAK mode (single character processing)
-cbreak	turns off CBREAK mode (line-at-a-time processing)

Charoptions  represent variables in the terminal interface, and are as follows:

intr c	sets the interrupt character (normally ^C)
start c	sets the start character (normally ^Q)
stop c	sets the stop character (normally ^S)
eof c	sets the eof character (normally ^D)
susp c	sets the suspend character (normally ^Z)

c may be defined either as an octal number such as 003, or in control character format (^C).

SEE ALSO
tty(4)

NAME
sum - print checksum and block count of a file

SYNOPSIS
sum [ file ]

DESCRIPTION
Sum calculates and prints a 16-bit checksum for the named file, and also prints the number of blocks in the file. Stdin is used if no file names are given.  Sum is typically used to look for corrupted files, or to validate a file communicated over some transmission line.

DIAGNOSTICS
``Read error'' is indistinguishable from end of file on most devices; check the block count.

SEE ALSO
wc(1).

NOTE
Sum is pretty slow on large files when running on the GS.  If anyone has a faster algorithm for computing the 16-bit  checksum, I'd really appreciate seeing it. 

AUTHOR
Marek Pawlowski - marekp@pnet91.cts.com

NAME
sx, sb, sz - Send Files with ZMODEM, YMODEM, or XMODEM
zcommand, zcommandi - Send COmmands with ZMODEM

SYNOPSIS
sz [-+abdefkLlNnopTtuvyYZ] file ...
sb [-dfktuv] file ...
sx [-ktuv] file
zcommand [-otv] COMMAND
zcommandi [-otv] COMMAND
sz -TT

DESCRIPTION
Sz (send ZMODEM) uses the ZMODEM, YMODEM or XMODEM error correcting protocol to send one or more files over a dial-in serial port to a variety of programs running under PC-DOS, CP/M, Unix, VMS, and other operating systems.

This is a shareware program copyrighted by Omen Technology INC.

Sz sends one or more files with ZMODEM protocol.

ZMODEM greatly simplifies file transfers compared to XMODEM. In addition to a friendly user interface, ZMODEM provides Personal Computer and other users an efficient, accurate, and robust file transfer method.

ZMODEM provides complete END-TO-END data integrity between application programs. ZMODEM's 32 bit CRC catches errors that sneak into even the most advanced networks.

Advanced file management features include AutoDownload (Automatic file Download initiated without user intervention), Display of individual and total file lengths and transmission time estimates, Crash Recovery, selective file transfers, and preservation of exact file date and length.

The -y option instructs the receiver to open the file for writing unconditionally.  The -a option causes the receiver to convert Unix newlines to PC-DOS carriage returns and linefeeds.

Sb sends one or more files with YMODEM or ZMODEM protocol. The initial ZMODEM initialization is not sent.  When requested by the receiver, sb supports YMODEM-g with "cbreak" tty mode, XON/XOFF flow control, and interrupt character set to CAN (^X).  YMODEM-g increases YMODEM throughput over error free channels (direct connection, X.PC, etc.) by disabling error recovery.

On Unix systems, additional information about the file is transmitted. If the receiving program uses this information, the transmitted file length controls the exact number of bytes written to the output dataset, and the modify time and file mode are set accordingly.

Sx sends a single file with XMODEM or XMODEM-1k protocol (sometimes incorrectly called "ymodem").  The user must supply the file name to both sending and receiving programs.

If sz is invoked with $SHELL set and if that variable contains the string rsh or rksh (restricted shell), sz operates in restricted mode. Restricted mode restricts pathnames to the current directory and PUBDIR (usually /usr/spool/uucppublic) and/or subdirectories thereof.

The fourth form sends a single COMMAND to a ZMODEM receiver for execution.  Zcommand exits with the COMMAND return value.  If COMMAND includes spaces or characters special to the shell, it must be quoted.

The fifth form sends a single COMMAND to a ZMODEM receiver for execution.  Zcommandi exits as soon as the receiver has correctly received the command, before it is executed.

The sixth form (sz -TT) attempts to output all 256 code combinations to the terminal. If you are having difficulty sending files, this command lets you see which character codes are being eaten by the operating system.

The meanings of the available options are:

+	Instruct the receiver to append transmitted data to an existing file (ZMODEM only).
a	Instruct the ZMODEM receiver to convert text file format as appropriate for the receiving system. Valid only for ZMODEM.
b (Zmodem)	Binary override: transfer file without any translation.
c	Instruct the receiver to change the pathname if the destination file exists.
d	Change all instances of "." to "/" in the transmitted pathname. Thus, C.omenB0000 (which is unacceptable to MSDOS or CP/M) is transmitted as C/omenB0000.  If the resultant filename has more than 8 characters in the stem, a "." is inserted to allow a total of eleven.
e	Escape all control characters; normally only XON, XOFF, DLE, CR-@-CR, and Ctrl-X are escaped.
f	Send Full pathname.  Normally directory prefixes are  stripped from the transmitted filename.
k (X/Ymodem)	Send files using 1024 byte blocks rather than the default 128 byte blocks. 1024 byte packets speed file transfers at high bit rates. (ZMODEM streams the data for the best possible throughput.)
L N	Use ZMODEM sub-packets of length N.  A larger N (32 <=  N <= 1024) gives slightly higher hroughput, a smaller N speeds error recovery. The default is 128 below 300 baud, 256 above 300 baud, or 1024 above 2400 baud.
l N	Wait for	the receiver to acknowledge correct data every N (32 <= N <= 1024) characters. This may be used to avoid network overrun when XOFF flow control is lacking.
n (Zmodem)	Send each file if destination file does not exist. Overwrite destination file if source file is newer than the destination file.
N (Zmodem)	Send each file if destination file does not exist. Overwrite destination file if source file is newer or longer than the destination file.
o (Zmodem)	Disable automatic selection of 32 bit CRC.
p (Zmodem)	Protect existing destination files by skipping  transfer if the destination file exists.
r (Zmodem)	Resume interrupted file transfer.  If the source file is longer than the destination file, the transfer commences at the offset in the source file that equals the length of the destination file.
rr 	As above, but compares the files (the portion common to sender and reciever) before resuming the transfer.
t tim	Change timeout to tim tenths of seconds.
u	Unlink the file after successful transmission.
w N  	Limit the transmit window size to N bytes (ZMODEM).
v	Verbose causes a list of file names to be appended to /tmp/szlog. More v's generate more output.
y	Instruct a ZMODEM receiving program to overwrite any existing file with the same name.
Y	Instruct a ZMODEM receiving program to overwrite any existing file with the same name, and to skip any source files that do have a file with the same pathname on the destination system.
Z	Use ZMODEM file compression to speed file transfer.

DIAGNOSTICS
Exit status is as follows: 0 for successful transfers.  1 if unrecoverable errors are detected.  2 if syntax errors or file access problems are detected.  3 if the program was terminated by a caught interrupt.

EXAMPLE
ZMODEM File Transfer (GNO to remote system)
% sz -a *.c
This single command transfers all .c files in the current directory with conversion (-a) to end of line conventions appropriate to the receiving environment. With ZMODEM AutoDownload enabled, will automatically recieve the files after performing a security check.

% sz -Yan *.c *.h
Send only the .c and .h files that exist on both systems, and are newer on the sending system than the corresponding version on the receiving system, converting Apple to UNIX text format.

SEE ALSO
rz(1).

Compile time options required for various operating systems are described in the source file.

FILES
32 bit CRC code courtesy Gary	S. Brown.

sz.c, crctab.c, rbsb.c, zm.c, zmr.c, zmodem.h Unix source files

/tmp/szlog stores debugging output (sz -vv)

TESTING FEATURE
The command "sz -T file" exercises the Attn sequence error recovery by commanding errors with unterminated packets. The receiving program should complain five times about binary data packets being too long.  Each time sz is interrupted, it should send a ZDATA header followed by another defective packet.  If the receiver does not detect five long data packets, the Attn sequence is not  interrupting the sender, and the Myattn string in sz.c must be modified.

After 5 packets, sz stops the "transfer" and prints the total number of characters "sent" (Tcount).  The difference between Tcount and 5120 represents the number of characters stored in various buffers when the Attn sequence is generated.

NOTES
When using buffered modems at high speed, particular attention must be paid to flow control. The modem and Unix must agree on the flow control method. Sz on USG (SYS III/V) systems uses XON/XOFF flow control. If flow control cannot be properly set up, Try a "-w 2048" option to enforce protocol level flow control.  Experiment with different window sizes for best results.

If a program that does not properly implement the specified file transfer protocol causes sb to "hang" the port after a failed transfer, either wait for sb to time out or type a dozen Ctrl-X characters.

Many programs claiming to support YMODEM only support XMODEM with 1k blocks, and they often don't get that quite right. XMODEM transfers add up to 127 garbage bytes per file. XMODEM-1k and YMODEM-1k transfers use 128 byte blocks to avoid extra padding.

YMODEM programs use the file length transmitted at the beginning of the transfer to prune the file to the correct length; this may cause problems with source files that grow during the course of the transfer. This problem does not pertain to ZMODEM transfers, which preserve the exact file length unconditionally.

Most ZMODEM options are merely passed to the receiving program; some programs do not implement all of these options.

Circular buffering and a ZMODEM sliding window should be used when input is from pipes instead of acknowledging frames each 1024 bytes. If no files can be opened, sz sends a ZMODEM command to echo a suitable complaint; perhaps it should check for the presence of at least one accessible file before getting hot and bothered.

BUGS
On at least one BSD system, sz would abnormally end if it got within a few kilobytes of the end of file.  Using the "-w 8192" flag fixed the problem.  The real cause is unknown, perhaps a bug in the kernel TTY output routines.

The test mode leaves a zero length file on the receiving system.

GNO/ME
The usual manner of invoking sz to send files from a IIgs is as follows:

Connect to the other computer with a term program such as TelCom GS

Start the X/Y/Zmodem receive on the other side

Get/Quit back to the GNO Shell

Type:
sz -v -v -b filename1 filename2 .. <.ttya >.ttyb

You may put this operation in the background of course. Tests have shown no data loss up to 9600 baud in background operation.

The -b option ensures binary mode.  You must use this if you're sending a ShrinkIt archive or other binary file.  For plain text files you can leave off the -b.

NAME
tar - extract and view tape archives

SYNOPSIS
tar [-]{x|t}f[v] archive

DESCRIPTION
tar lists the contents of and extracts files from UNIX tape archives (*.tar files).

Traditionally, tar does not require the normal '-' character to denote its arguments.  The option flags are as follows:

-x	Extract files from the archive
-v	Verbose mode (tell what tar is doing)
-t	Tell mode (list files in archive)
-f	Use a file on disk instead of a tape

Since the standard IIGS filesystem is not as flexible, filename-wise, as UNIX filesystems, some pre-processing is performed on filenames created when an archive is extracted.

• If a tar filename contains a double-/ (possible under UNIX if an archive was created by specifying a directory with a trailing slash), tar converts it to a single /.

• If a filename contains non-alpha numeric characters, they are converted to periods ('.').

tar does not maintain the file protection bits from UNIX, nor does it maintain the creation and modification dates.

BUGS
Does not create .tar archives
Does not work with raw devices, only files
Does not allow user to specify which files to extract from archive
tar should use the GS/OS JudgeName call.
The -x and -t options should be exclusive, but are not.

NAME
tee - Pipe fitting.

SYNOPSIS
tee [ -ai ] [ file ...]

DESCRIPTION
The tee utility copies standard input to standard output, making a copy in zero or more files.  The output is unbuffered.

The following options are available:

-a	Append the output to the files rather than overwriting them.

-i	Ignore the SIGINT signal.

The following operands are available:

file	A pathname of an output file .

The tee utility takes the default action for all signals, except in the event of the -i option.

The tee utility exits 0 on success, and >0 if an error occurs.

STANDARDS
The tee function is expected to be POSIX p1003.2 compatible.

SEE ALSO
GNO/Shell User's Manual , signal(2)

NAME
time - time a command

SYNOPSIS
time command

DESCRIPTION
The time command lets the specified command 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.

The time command can be used to cause a command to be timed no matter how much 
CPU time it takes.  For example:

% /bin/time cp /etc/rc /usr/bill/rc
        0.1 real         0.0 user         0.0 sys

% /bin/time nroff sample1 > sample1.nroff
        3.6 real         2.4 user         1.2 sys

This example indicates that the cp command used negligible amounts of user ( user ) and system time ( sys ), and had an elapsed time ( real ) of 1/10 second (0.1).  The nroff command used 2.4 seconds of user time and 1.2 seconds of system time, and required 3.6 seconds of elapsed time.

RESTRICTIONS
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.

NAME
tr - translate characters

SYNOPSIS
tr [ -cds ] [ string1 [ string2 ] ]

DESCRIPTION
tr copies the standard input to the standard output with substitution or deletion of selected characters.  The arguments string1 and string2 are considered sets of characters.  Any input character found in string1 is mapped into the character in the corresponding position within string2.  When string2 is short, it is padded to the length of string1 by duplicating its last character.

In either string the notation 'a - b' denotes a range of characters from a to 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.

When string2 is short, characters in string1 with no corresponding character in string2 are not translated.

In either string the following abbreviation conventions introduce ranges of characters or repeated characters into the strings.

[ a - z ]
	Stands for the string of characters whose ASCII codes run from character a to character z, inclusive.

[ a * n ]
	Stands for n repetitions of a.  If the first digit of n is 0, n is considered octal; otherwise, n is taken to be decimal.  A zero or missing n is taken to be huge; this facility is useful for padding string2.

OPTIONS
Any combination of the options -c, -d, or -s may be used:

-c	Complement the set of characters in string1 with respect to the universe of characters whose ASCII codes are 01 through 0377 octal;

-d	Delete all input characters in string1.

-s	Squeeze all strings of repeated output characters that are in string2 to single characters.

EXAMPLE
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.

tr -cs A-Za-z '\012' < filename1 > filename2

SEE ALSO
conv(1), more(1)

BUGS
Will not handle ASCII NUL in string1 or string2.  tr always deletes NUL from input.

NAME
unshar - extracts files from shar archives

SYNOPSIS
unshar {-overwrite} {-nosort} file1 file2 ...

DESCRIPTION
Unshar is a utility which extracts files from the ubiquitous Unix shar archives. It has the following advantages over existing unshar utilities:

- Small and fast
- Handles many cat and sed formats
- Allows extraction of subdirectories
- Understands ./file type filenames
- Understands file continuation with >>
- Sorts file list by Subject: line
- Exits cleanly with CTRL-C

Unshar 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.

Invoke unshar 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, unshar 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.

OPERATION
Unshar 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.

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.

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.

To assist with this, unshar 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 unshar can't find such an issue reference, it will look for a Part number and use that instead.

Unshar 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 unshar says "Extending file" rather than "Unsharing file".

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.

HISTORY
V1.0	First release.

V1.1	Added support for some more unusual uses of sed. 
	Increased speed, and reduced size slightly.
	Fixed bug that truncated lines longer than 80 chars.

V1.2	Added support for sorting by Subject: line
	Added support for file appending via >> 
	Fixed small bug in detection of disk write errors

AUTHOR
Eddy Carroll (EMAIL: ecarroll@vax1.tcd.ie)
Apple //gs port by Andy McFadden (fadden@uts.amdahl.com).

NAME
wc - display a count of lines, words and characters

SYNOPSIS
wc [ -lwc ] [ filename ... ]

DESCRIPTION
wc counts lines, words, and characters in filename 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.

OPTIONS
When filename s are specified on the command line, their names will be printed along with the counts.

The default is -lwc (count lines, words, and characters).

-l	Count lines.
-w	Count words.
-c	Count characters.

EXAMPLE
example% wc $USRMAN/csh.1 $USRMAN/sh.1 $USRMAN/telnet.1
1876    11223   65895   /usr/share/man/man1/csh.1
674     3310    20338   /usr/share/man/man1/sh.1
260     1110    6834    /usr/share/man/man1/telnet.1
2810    15643   93067   total
example%

NAME
who - who is on the system

SYNOPSIS
who [ who-file ] [ am I ]

DESCRIPTION
Who, without an argument, lists the login name, terminal name, and login time for each current UNIX user.

Without an argument, who examines the /etc/utmp file to obtain its information.  If a file is given, that file is examined. Typically the given file will be /usr/adm/wtmp, which contains a record of all the logins since it was created. Then who 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.

With two arguments, as in `who am I' (and also `who are you'), who tells who you are logged in as.

FILES
/etc/utmp

SEE ALSO
getuid(2), utmp(5)

NAME
yes - be repetitively affirmative

SYNOPSIS
yes [ expletive ]

DESCRIPTION
Yes repeatedly outputs "y", or if expletive is given, that is output repeatedly. Termination is by interrupt.

NAME
alarm - set and reset alarm timer

SYNOPSIS
#include <gno/gno.h>
long int alarm(long int seconds);

DESCRIPTION
alarm sets the counter on the calling process' alarm timer to the value specified in seconds.  If seconds is (long int) 0, the alarm timer is disabled.

When an alarm timer terminates (by counting down to 0), the calling process is sent a SIGALRM signal.

RETURN VALUE
The amount of time previously remaining in the timer is returned.  No errors are possible.

SEE ALSO
signal(2), sigpause(2)

NAME
dup,dup2 - duplicate open file descriptors

SYNOPSIS
#include <gno/gno.h>

int dup(int filedes);
int dup2(int filedes, int filedes2);

DESCRIPTION
Given the file descriptor of a valid open file, dup creates a new file descriptor that is synonymous with filedes.  The new file descriptor is returned.  The second form of the call forces an existing file descriptor filedes2 to refer to the same file as filedes.  If filedes2 already refers to an open file, it is closed first.

RETURN VALUE
dup returns the new file descriptor, and dup2 returns 0 if the calls are successful.  In the event of an error, -1 is returned and errno is set as follows:

[EBADF]	filedes refers to an invalid file descriptor (not an open file)
[EMFILE]	no more files can be opened; process is at current limit (32).

SEE ALSO
fork(2), open(2)

NAME
execve - replace current process with an executable image from a file

SYNOPSIS
#include <gno/gno.h>
int execve(char *pathname, char *cmdline);

DESCRIPTION
execve 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. pathname can be a partial or complete path.  The executable loaded replaces the executable associated with  the current process.

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).

The parameter cmdline 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(). cmdline can be accessed from assembly langugage through the X (high-order word of cmdline) and Y (low-order word) registers.  However, if the executable file is of file type S16 ($B3), the cmdline 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 cmdline  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 shellid().  The A register is set to the userID allocated for the process.

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).
The following information is inherited by the new executable: current machine state, controlling TTY, process group ID, and prefixes 0 and 8.  

Caught signals are reset to the default action. Ignored signals remain ignored across the execve.  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.

RETURN VALUE
A successful execve 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 errno is set to one of the following:
[ENOENT]	the pathname specified does not exist
[EIO]		some general I/O error occurred trying to load the executable

BUGS
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 GNO Kernel Reference Manual for more information on this topic.  ORCA/C 2.0 and newer use the system-provided stack space.

SEE ALSO
exec(2), fork(2), wait(2), ioctl(2), tty(4), GNO Kernel Reference Manual

NAME
fork - start a new process from inside the current application space

SYNOPSIS
#include <gno/gno.h>

int fork(void *addr);

DESCRIPTION
fork's argument addr is typically the address of a C function, although it can be any valid address inside the IIGS RAM space.  fork 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:

	A	the userID assigned to the process
	X	0
	Y	0

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.

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.

RETURN VALUE
fork returns the process ID of the child, or -1 (SYSERR) if an error occurs, in which case errno is set as follows:
	[ENOMEM]	not enough memory to create the new process
	[EAGAIN]	all process slots full; no more can be created

NOTES
There is no way to pass parameters directly to a child with fork(). Use fork2() instead.

CAVEATS
Most UNIX forks 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 fork will have to be modified slightly to work under GNO.

SEE ALSO
fork2(2), exec(2), execve(2), wait(2), screate(2)

NAME
getpid, getpgrp, getppid - return information about processes

SYNOPSIS
#include <gno/gno.h>

int getpid(void);
int getpgrp(int pid);
int getppid(void);

DESCRIPTION
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 getpid 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.

getpgrp returns the process group ID of the specified process, pid.  This function is usually used when you wish to send a signal to all members of a process group using kill(2).

RETURN VALUE
getpid:	The process ID of the caller is returned.  No errors are possible.
getppid:	The process ID of the caller's parent is returned. No errors are possible.
getpgrp:	The process group ID of the specified process is returned.  In the event of an error, getpgrp returns -1 and sets errno to the appropriate error code:
[ESRCH]	pid is not a valid process ID

NOTES
getpgrp() 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.

SEE ALSO
fork(2), job control(2), ioctl(2), GNO Kernel Reference Manual

NAME
getuid, geteuid, getgid, getegid - get user and group identity
getpgrp - get process group

SYNOPSIS
#include <sys/types.h>
uid_t = getuid(void)
uid_t = geteuid(void)
gid_t = getgid(void)
gid_t = getegid(void)

DESCRIPTION
Getuid returns the real user ID of the current process, geteuid 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.

Getgid returns the real group ID of the current process, getegid 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.

NOTES
The setr*() functions are not currently implemented in GNO/ME, because set-uid and set-group-ID behavior is specific to the UNIX filesystem.

SEE ALSO
setreuid(2), setregid(2), setgid(3), tty(4)

NAME
intro - introduction to GNO system calls

DESCRIPTION
This section describes, in alphabetical order, the system calls and kernel interfaces available for GNO. Certain distinctions of purpose are made in the headings. 

Manual Page Command Syntax
Unless otherwise noted, calls described in the SYNOPSIS  section of a manual page accept parameters and require the

name  [- option ...] [ cmdarg ...]

where:

[]	Surround an option or cmdarg that is not required.

...	Indicates multiple occurrences of the option or cmdarg.

name 	The name of an executable file.

option 	(Almost always preceded by a "-".)
	noargletter ... or,
	argletter optarg [,...]

noargletter 	A single letter representing an option without an option-argument. Note that more than one noargletter option can be grouped after one "-".

argletter 	A single letter representing an option requiring an option-argument.

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.

cmdarg 	Path name (or other command argument)  not  beginning with a "-", or "-" by itself indicating the standard input.

SEE ALSO
GNO/ME Kernel Reference Manual

NAME
ioctl - control device

SYNOPSIS
#include <sys/ioctl.h>

int ioctl(int fd, unsigned long request, void *argp)

DESCRIPTION
Ioctl 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 ioctl requests.  The writeups of various devices in section 4 discuss how ioctl applies to them.

An ioctl request 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 ioctl request are located in the file <sys/ioctl.h>.

RETURN VALUE
If an error has occurred, a value of -1 is returned and errno is set to indicate the error.

ERRORS
Ioctl will fail if one or more of the following are true:

[EBADF]	Fd is not a valid descriptor.

[ENOTTY]	Fd is not associated with a character special  device.

[ENOTTY]	The specified request does not apply to the  kind of object that the descriptor fd references.

[EINVAL]	Request or argp is not valid.

SEE ALSO
execve(2), tty(4)

NAME
tcnewpgrp, settpgrp, tctpgrp - interface for the new job control model

SYNOPSIS
#include <gno/gno.h>

int tcnewpgrp(int fdtty);
int settpgrp(int fdtty);
int tctpgrp(int fdtty, int pid);

DESCRIPTION
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).  

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 ioctl(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.

tcnewpgrp(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.

settpgrp(fdtty): Sets the current process to have the same process group as fdtty.

tctpgrp(fdtty,pid): Sets the tty to the same process group as pid, where pid is the current process or a descendant of it. 

RETURN VALUE
The calls will return 0 if no error occurs; otherwise, they'll return -1 and set errno to one of the following:
[EBADF]	fdtty is not a valid file descriptor
[ENOTTY]	fdtty does not refer to a terminal file
[ESRCH]	pid is not a valid process identifier

NOTES
Following are some example uses of the job control interface.

•	Forking a pipeline in a job-control shell: The shell starts with tcnewpgrp(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 settpgrp(fdtty), thus joining the new process group.

•	Handling a stopped child process: When the shell sees that a pipeline has stopped or exited, it does tctpgrp(fdtty,getpid()) to set the tty to its own process group. To resume the pipeline it does tctpgrp(fdtty,pid) where pid is one of the child processes, then sends SIGCONT.

•	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 tcnewpgrp(fdtty) to give the tty a real process group, then settpgrp(fdtty) to place itself into the foreground.

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 tcnewpgrp(), in which case nobody else is using the pgrp, or tctpgrp(), 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.

SEE ALSO
ioctl(2), tty(4), signal(2), kill(2), GNO Shell Reference Manual

CREDITS
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.
The GNO/ME implementation was written strictly from specs.

NAME
kill - send a signal to a process

SYNOPSIS
#include <gno/gno.h>

int kill(int pid, int sig)

DESCRIPTION
kill 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 signal(2).

sig 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 sig has been blocked (sigblock(2)), the signal is deferred until it is unblocked, and kill returns immediately.  Any previously pending signals of the same sig are lost (i.e. signals are not stacked).

If pid is 0, the signal is sent to all processes with the same process group ID as the caller, except for system processes.

Processes may signal themselves, in which case the signal handler is invoked immediately (if one is installed).

RETURN VALUE
Normally kill returns SYSOK (0).  The following conditions can cause kill to return SYSERR (-1):
[ESHRC]	pid does not correspond to an existing process
[EINVAL]	sig specifies an invalid signal number

SEE ALSO
sigblock(2), signal(2), wait(2)

BUGS
Do not attempt to send signals from inside a CDA (Classic Desk Accessory) or interrupt handler.

NAME
pipe - create an interprocess communication channel

SYNOPSIS
#include <gno/gno.h>
int pipe(int filedes[2]);

DESCRIPTION
The pipe 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 filedes[1] up to 4096 bytes of data are buffered before the writing process is suspended.  A read using the descriptor filedes[0] will pick up the data.

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.

The shell has a syntax to set up a linear array of processes connected by pipes.

Read calls on an empty pipe (no buffered data) with only one end (all write file descriptors closed) returns an end-of-file.

A signal (SIGPIPE) is generated if a write on a pipe with only one end is attempted.

RETURN VALUE
The function value zero is returned if the pipe was created; -1 if an error occurred.

ERRORS
The pipe call will fail if:
[EMFILE]	Too many descriptors are active.
[ENFILE]	The system file table is full.
[EFAULT]	The fildes buffer is in an invalid area of the process's address space.

SEE ALSO
GNO Shell Users Manual, read(2), write(2), fork(2)

BUGS
Should more than 4096 bytes be necessary in any pipe among a loop of processes, deadlock will occur.

NOTES
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.

NAME
screate, sdelete, swait, ssignal - semaphore operations

SYNOPSIS
#include <gno/gno.h>

int swait(int sem);
int ssignal(int sem);
int screate(int count);
int sdelete(int sem);

DESCRIPTION
screate 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).

The initial count determines how many times swait can be called before processes are blocked. count must be >= 0, and is usually set to 1. screate returns a semaphore ID number as an integer.  This ID must be used in all the other semaphore calls.

sdelete releases the specified semaphore, and returns all processes that were blocked to a ready state.

swait decrements the value of the semaphore (initially specified by count ) by 1. If the semaphore count is less than zero, the process is blocked and queued for release by ssignal.

ssignal increments the semaphore count by one.  If the semaphore count is less than zero, ssignal releases arbitrarily a process that had been blocked; FIFO operation is not guaranteed.

RETURN VALUE
All the functions return SYSERR (-1) if an error occurs, and an OK (0) if no error occurs.

BUGS
There is currently no mechanism for deallocating semaphores that are orphaned by abnormal process termination.

HISTORY
These semaphore routines were designed for XINU, written by Douglas Comer.

NAME
setdebug - set debugging output options

SYNOPSIS
#include <gno/gno.h>

int setdebug(int options);

DESCRIPTION
setdebug 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>.

dbgGSOS	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.

dbgPATH	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: "EP: <fullpath>".

dbgERROR	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 dbgGSOS is also enabled.

dbgSIG	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: "kill (-signum): pid: tpid".

dbgSYSCALL	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 execve(2), fork(2), and the job control routines.

dbgPBLOCK	The memory address of GS/OS and Shell parameter blocks is printed for each call.  As with dbgERROR, this option has no effect unless dbgGSOS is also enabled.

RETURN VALUE
setdebug returns the previous value of the debug options word.

SEE ALSO
fork(2),execve(2),ioctl(2),kill(2)

BUGS
Due to problems associated with signals that are sent during process termination, dbgSIG prints its information to standard output instead of standard error.

NAME
sigblock,sigmask  - temporarily block signals

SYNOPSIS
#include <signal.h>

long sigblock(long mask);
#define sigmask(signum)

DESCRIPTION
sigblock is used to temporarily block the reception of signals.  The input parameter mask 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.

sigmask is a macro that can be used to calculate signal masks for sigblock.  It takes a signal number (signum) as an argument and returns a mask that can then be passed to sigblock.

If a signal is sent to a process but is blocked, the event is recorded for later release by sigsetmask(2).  Blocked signals are not stacked; further occurrences of a blocked signal will overwrite any previous pending signal of the same signum.

It is not possible to block SIGKILL, SIGCONT, or SIGSTOP. This restriction is silently enforced by the system.

RETURN VALUE
The previous value of the signal mask is returned.

SEE ALSO
kill(2), sigsetmask(2), signal(2)

NAME
signal - a simplified software signal interface

SYNOPSIS
#include <signal.h>

void (*signal(int sig; void (*func(void))(void)

DESCRIPTION
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 (kill); stack overflow; a process making an input request while running in the background; an attempt to write to a pipe with no reader.

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).

	SIGHUP	1	hangup
	SIGINT	2	interrupt
	SIGQUIT	3	quit
	SIGILL	4	illegal instruction
	SIGTRAP	5	trace trap
	SIGABRT	6	abort (generated by abort(3) routine) 
	SIGEMT	7	emulator trap 
	SIGFPE	8	arithmetic exception 
	SIGKILL	9	kill (cannot be caught, blocked, or ignored) 
	SIGBUS	10	bus error 
	SIGSEGV	11	segmentation violation 
	SIGSYS	12	bad argument to system call 
	SIGPIPE	13	write on a pipe or other socket with no one to read it 
	SIGALRM	14	alarm clock 
	SIGTERM	15	software termination signal 
	SIGURG	16@	urgent condition present on socket 
	SIGSTOP	17 | +	stop (cannot be caught, blocked, or ignored) 
	SIGTSTP	18 | +	stop signal generated from keyboard 
	SIGCONT	19@	continue after stop (cannot be blocked) 
	SIGCHLD	20@	child status has changed 
	SIGCLD	20	System V name for SIGCHLD 
	SIGTTIN	21 | +	background read attempted from control terminal 
	SIGTTOU	22 | +	background write attempted to control terminal 
	SIGIO	23@	input/output possible on a file descriptor 
	SIGPOLL	SIGIO	System V name for SIGIO 
	SIGXCPU	24	exceeded CPU time limit 
	SIGUSR1	30	user defined signal 1 
	SIGUSR2	31	user defined signal 2 

If func 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 func 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.

If a signal occurs during certain system calls (wait(), and input from a TTY), the call is automatically restarted upon return from the handler.

A forked child inherits all signal information, including pending signals and blocking and handler information. exec() and execve() restore all signal information to defaults and purge pending signals.

NOTES
The signal handler should be defined as follows:

void handler (int sig, int code)

sig is the signal that invoked the handler, and code is additional information about the interrupt condition.  Currently, code 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).

RETURN VALUE
The previous action is returned on a successful call. Otherwise,  -1 is  returned.  [EINVAL] will occur on any of the following conditions:
sig specifies an invalid signal number.
An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP.
An attempt is made to ignore SIGCONT (by default SIGCONT is ignored).

CAVEATS
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.

SEE ALSO
execve(2), fork(2), kill(2), sigblock(2), sigsetmask(2), wait(2), tty(4)

NAME
sigpause - suspend process until a signal arrives

SYNOPSIS
#include <signal.h>
int sigpause(long int mask);

DESCRIPTION
sigpause suspends execution of the calling process until a signal arrives.  The mask parameter is assigned to the set of blocked signals (sigsetmask), 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 mask is 0 (zero) to pause until any signal arrives.

sigpause 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.

RETURN VALUE
sigpause always returns an error (-1) and sets errno to EINTR.

SEE ALSO
signal(2), sigblock(2), sigsetmask(2)

NAME
sigsetmask  - set signal mask

SYNOPSIS
#include <signal.h>

long sigsetmask(long mask);
#define sigmask(signum)

DESCRIPTION
sigsetmask is usually used to restore signal masks after modification by sigblock.  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).

If there are pending instances of signals which become unblocked by the sigsetmask 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).

sigmask is a macro that can be used to calculate signal masks for sigsetmask.  It takes a signal number, as listed in signal(2), as an argument and returns a mask corresponding to that signal.

RETURN VALUE
The previous value of the signal mask is returned.

CAVEATS
If somehow the process re-blocks a signal released by sigsetmask before the system signal queue processes it, it will be blocked and marked as pending. This can happen if a signal handler makes a sigblock call.  

SEE ALSO
kill(2), sigblock(2), signal(2)

NAME
stat, fstat, lstat - return status information on indicated files

SYNOPSIS
#include <sys/stat.h>

int stat(const char *filename, struct stat *s_buf);
int fstat(int filedes, struct stat *s_buf);
int lstat(const char *filename, struct stat *s_buf);

DESCRIPTION
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.

stat takes arguments filename, a NUL-terminated string naming the file to get information on, and s_buf, a pointer to a stat structure, defined in <sys/stat.h>.  filename can be a partial or a complete path.  The miscellaneous types in struct stat, below, are defined in <sys/types.h>, automatically included by stat.h.

struct stat {
  dev_t	st_dev;	/* ID number of device file resides on */
  ino_t	st_ino;	/* inode number of file */
  unsigned short st_mode;	/* type of file and mode */
  short	st_nlink;	/* number of links to file = 0 */
  uid_t	st_uid;	/* user id = 0 */
  gid_t	st_gid;	/* group id = 0 */
  dev_t	st_rdev;	/* device type ID */
  off_t	st_size;	/* length of file in bytes */
  time_t	st_atime;	/* last access time (same as mod time on Apple IIGS) */
  int	st_spare1;	/* reserved */
  time_t	st_mtime;	/* last modification time */
  int	st_spare2;	/* reserved */
  time_t	st_ctime;	/* file creation time */
  int	st_spare3;	/* reserved */
  long	st_blksize;	/* size in bytes of blocks on filesystem */
  long	st_blocks;	/* number of blocks file uses */
  long	st_spare4[2];	/* reserved */
};

The items marked 'reserved' are not currently used but are reserved for future expansion; do not use these fields for any reason.  st_dev is the device number the file resides on.  This number is the same as the GS/OS device ID number.  st_rdev is not currently used, but may in the future designate a device type code.

st_mode is a bit field representing access mode and type of the file.  The flags in st_mode are as follows:

#define S_IFDIR	0040000	/* directory */
#define S_IFCHR	0020000	/* character special */
#define S_IFBLK	0060000	/* block special */
#define S_IFREG	0100000	/* regular */
#define S_IFLNK	0120000	/* symbolic link */
#define S_IFSOCK	0140000	/* socket or pipe */
#define S_IREAD	0000400	/* read permission, owner */
#define S_IWRITE	0000200	/* write permission, owner */
#define S_IEXEC	0000100	/* file is an executable, owner */

fstat is similar to stat except the argument is an open file descriptor filedes.  If filedes refers to a character device or pipe, the entire s_buf is set to 0 and only st_mode and st_dev are set.

lstat is similar to stat, but if the filename is a link then information is returned about the link file instead of the file linked to.

RETURN VALUE
If the call completes without mishap, stat returns a 0.  If an error occurs, stat returns -1 and sets errno to one of the following:

[ENOENT]	filename does not specify an existing file or directory
[ENOTDIR]	an element of filename is not an expected subdirectory

fstat can additionally return 
[EBADF]	filedes does not refer to an open file descriptor

BUGS
GNO does not yet support hard or  symbolic file links on the IIGS. Therefore, lstat operates exactly like stat.  But if there's a case where lstat might be appropriate at a time when links are supported, then use lstat instead and be ready for the future.

fstat doesn't do anything clever with all the unused fields in struct stat when its argument is a pipe or terminal.

NAME
statfs - get file system statistics

SYNOPSIS
#include <sys/vfs.h>

int statfs(char *path, struct statfs *buf)
int fstatfs(int fd, struct statfs *buf)

DESCRIPTION
statfs returns information about a mounted file system. path is the path name of any file within the mounted filesystem. Buf is a pointer to a statfs structure defined as follows:

typedef struct {
	long	val[2];
} fsid_t;

struct statfs {
	long	f_type; 	/* type of info, zero for now */
	long	f_bsize;	/* fundamental file system block size */
	long	f_blocks;	/* total blocks in file system */
	long	f_bfree;	/* free blocks */
	long	f_bavail;	/* free blocks available to non-superuser */
	long	f_files;	/* total file nodes in file system */
	long	f_ffree;	/* free file nodes in fs */
	fsid_t f_fsid; 	/* file system id */
	long	f_spare[7];	/* spare for later */
};

Fields that are undefined for a particular file system are set to -1. fstatfs returns the same information about an open file referenced by descriptor fd.

RETURN VALUE
Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

ERRORS
statfs fails if one or more of the following are true:

ENOTDIR	A component of the path prefix of path is not a directory.
EINVAL	path contains a character with the high-order bit set.
ENAMETOOLONG	The length of a component of path exceeds 255 characters, or the length of path exceeds 1023 characters.
ENOENT	The file referred to by path does not exist.
EACCES	Search permission is denied for a component of the path prefix of path.
EIO	An I/O error occurred while reading from or writing to the file system.

fstatfs fails if one or both of the following are true:

EBADF	fd is not a valid open file descriptor.
EIO	An I/O error occurred while reading from or writing to the file system.
NAME
truncate, ftruncate - set a file to a specified length

SYNOPSIS
#include <sys/types.h>

int truncate(char *path, off_t length)
int ftruncate(int fd, off_t length)

DESCRIPTION
truncate() causes the file referred to by path (or for ftruncate() the object referred to by fd ) to have a size equal to length bytes. If the file was previously longer than length , the extra bytes are removed from the file. If it was shorter, bytes between the old and new lengths are read as zeroes. With ftruncate(), the file must be open for writing.

RETURN VALUES
truncate() returns:
0	on success.
-1	on failure and sets errno to indicate the error.

ERRORS
truncate() may set errno to:

EACCES	Search permission is denied for a component of the path prefix of path.
	Write permission is denied for the file referred to by path .

EIO	An I/O error occurred while reading from or writing to the file system.

EISDIR	The file referred to by path is a directory.

ENAMETOOLONG	The length of the path argument exceeds {PATH_MAX}.
	A pathname component is longer than {NAME_MAX} (see sysconf (2V)) while {_POSIX_NO_TRUNC} is in effect (see pathconf (2V)).

ENOENT	The file referred to by path does not exist.

ENOTDIR	A component of the path prefix of path is not a directory.

EROFS	The file referred to by path resides on a read-only file system.

ftruncate() may set errno to:

EINVAL	fd is not a valid descriptor of a file open for writing.
	fd refers to a socket, not to a file.

EIO	An I/O error occurred while reading from or writing to the file system.

SEE ALSO
open (2)

BUGS
These calls should be generalized to allow ranges of bytes in a file to be discarded.

NAME
wait, WIFSTOPPED, WIFSIGNALED, WIFEXITED - wait for process to terminate or stop

SYNOPSIS
#include <sys/wait.h>

int wait(union wait *statusp);
WIFSTOPPED(union wait status);
WIFSIGNALED(union wait status);
WIFEXITED(union wait status);

DESCRIPTION
wait blocks the caller until a signal is received or one of its  child processes terminates.  If any child has died and this has not been reported using wait, return is immediate, returning the process ID and exit status of one of those children.  If that  child  had died, it is discarded.  If there are no children, return is immediate with the value -1 returned.  If there are processes that have not been reported by wait, the caller is blocked.

If status is not a NULL pointer, then on return from a successful wait call the status of the child process whose process ID is the return value of wait is stored in the wait union pointed to by status.  The wstatus member of that union is an int; it indicates the cause of termination and other information about the terminated process in the following manner:

•	If the low-order 8 bits of wstatus are equal to 0177 (hex 0xFF), the child process has stopped; the high-order 8 bits of wstatus contain the number of the signal that caused the process to stop.  See signal(2).

•	If the low-order 8 bits of wstatus are non-zero and are not equal to 0177, the child process terminated due to a signal; the low-order 7 bits of wstatus contain the number of the signal that terminated the process.

•	Otherwise, the child process terminated due to an exit() call; the high-order 8 bits of wstatus contain the low-order 8 bits of the argument that the child process passed to exit or GS/OS Quit.
 
Other members of the wait union can be used to extract this information more conveniently:

•	If the wstopval member has the value WSTOPPED, the child process has stopped; the value of the wstopsig member is the signal that stopped the process.

•	If the wtermsig member is non-zero, the child process terminated due to a signal; the value of the wtermsig member is the number of the signal that terminated the process. 

•	Otherwise, the child process terminated due to an exit()  call; the value of the wretcode member is the low-order 8 bits of the argument that the child process passed to exit().

The other members of the wait union merely provide an alternate way of analyzing the status.  The value stored in the wstatus field is compatible with the values stored by versions of the UNIX system, and an argument of type int * may be provided instead of an argument of type union wait * for compatibility with those versions.

WIFSTOPPED, WIFSIGNALED, WIFEXITED, are macros that take an argument status, of type `union  wait', as returned by wait().  WIFSTOPPED evaluates to true (1) when the process for which the wait call was made is stopped, or to false (0) otherwise. WIFSIGNALED  evaluates to true when the process was terminated with a signal. WIFEXITED evaluates to true when the process exited by using an exit(2) call.

If wait returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process.  Otherwise, a value of -1 is returned and errno is set to indicate the error.

ERRORS
wait will fail and return immediately if one or more of the following are true:

[ECHILD]	The calling process has no existing unwaited-for child processes.
[EFAULT]	The  status  or  rusage  arguments  point  to  an illegal address.
[EINTR]	The wait call was interrupted by a caught signal.

SEE ALSO
signal(2), exit(3), rexit(3), execve(2)

NOTES
If a parent process terminates without waiting on its children,  the Kernel Null Process (process ID = 0) inherits the children.

wait is automatically restarted when a process receives a signal while awaiting termination of a child process, if the signal is not caught; i.e. signal() handler value is SIG_DFL or SIG_IGN.

GSString255Ptr __C2GSMALLOC(char *s)
Converts a C-style string to a Class 1 GS/OS string, allocating space for the GS/OS string from C's malloc() routine.  You must specifically deallocate the string with free() when you're through with it.

char *__GS2CMALLOC(GSString255Ptr g)
Converts a Class 1 GS/OS string to a C-style string, allocating space for the C string from C's malloc() routine.  You must specifically deallocate the string with free() when you're through with it.

char *__GS2C(char *s, GSString255Ptr g)
Converts a Class 1 GS/OS string to a C string; the buffer space for the C string must be allocated beforehand by the caller.  The return value is the address of the C string passed as argument s.

int _mapErr(int err)
Tries to map a GS/OS error code (err) to a UNIX errno code (return value).  If there is no direct mapping, EIO is returned.

access

#include <unistd.h>
int access(char *name, int mode)

Returns TRUE (1) if the file specified by name can be acessed according to mode by the calling process.  Values of mode are declared in <unistd.h> and are as follows:
F_OK - returns true if the file exists
X_OK - returns true if the process has execution permissions for the file
W_OK - returns true if the process has write permissions for the file
R_OK - returns true if the process has read permissions for the file

bcopy  bzero

#include <string.h>
void bcopy(char *b1, char *b2, size_t n)
void bzero(char *buf, size_t n)

bcopy() copies n bytes from memory address b1 to memory address b2.  bcopy() is functionally similar to memcpy(), except that bcopy copies from the first argument to the second argument, whereas memcpy() copies from the second argument to the first argument.  If the memory areas overlap, the results are unpredictable.  bcopy() is provided for compatibility with BSD source code.

bzero() clears n bytes of memory starting at buf to 0 (zero). This call is functionally equivalent to memset(buf,0,n) and is included for BSD source code compatibilty.
See Also: memcpy, memset, ORCA/C 2.0 Manual

chdir

#include <unistd.h>
int chdir(const char *pathname)
Changes the current working directory (GS/OS prefix 0) to the pathname specified by pathname. If an error occurs changing the prefix, -1 is returned and the error code is placed in errno.

crypt

char *crypt(char *pw,char *salt)

crypt is used to encrypt passwords for storage in the /etc/passwd file, and also to validate passwords entered in the login and passwd programs. pw is the password to encrypt, a NUL- terminated string.  salt is a two- character encryption key that should be randomly generated by the caller in the case of encrypting a new password, or should be taken as the first two characters of the /etc/passwd password entry in the case of validating a password.

crypt returns a pointer to the encrypted password, which is formatted as printable ASCII characters and is NUL terminated.  A static buffer is used to hold the result, so to be sure the encrypted password is not overwritten by a subsequent call to crypt copy it before use.
See also: getpass, getpwent

errno strerror perror

char *strerror(int errnum)
void perror(char *s)
extern int errno;

These routines are as documented in the ORCA/C manual, except that they support the full range of GNO's errno codes.  errno is the variable that most library and kernel calls place their return status in.  The codes are defined symbolically in <errno.h> and are listed here:
	EDOM	domain error
	ERANGE	number too large, too small, or illegal
	ENOMEM	Not enough memory
	ENOENT	No such file or directory
	EIO		I/O error
	EINVAL	Invalid argument
	EBADF	bad file descriptor
	EMFILE	too many files are open
	EACCESS	access bits prevent the operation
	EEXIST	the file exists
	ENOSPC	the file is too large
	EPERM	Not owner
	ESRCH	No such process
	EINTR	Interrupted system call
	E2BIG	Arg list too long
	ENOEXEC	Exec format error
	ECHILD	No children
	EAGAIN	No more processes
	ENOTDIR	Not a directory
	ENOTTY	Not a terminal
	EPIPE	Broken pipe
	ESPIPE	Illegal seek
	ENOTBLK	not a block device
	EISDIR	not a plain file

fsync

int fsync(int fd)

Causes the operating system to flush any I/O buffers associated with the file referenced by file descriptor fd to disk.  This ensures that all information is up to date, in the event of a system crash.  This call is only needed in special circumstances, as when several daemon processes are all modifying the same file simultaneously (currently impossible with existing IIGS filesystems).  This call is basically a FlushGS.

ftruncate

int ftruncate(int fd, off_t length)

Causes the EOF marker for the file specified by file descriptor fd to be set to length.  In the event of an error, ftruncate returns -1 and sets errno.

getgrnam  getgrgid  getgrent  setgrent  setgroupent  endgrent

#include <sys/types.h>
#include <grp.h>
struct group *getgrnam(const char *name);
struct group *getgrgid(gid_t gid);
struct group *getgrent(void);
int setgrent(void);
int setgroupent(int stayopen);
void endgrent(void);
(POSIX)

This family of functions should be used to access the groups database; applications should never read /etc/groups directly, as the implementation of the groups database is subject to change.

getgrnam() reads the group database based on group name.  It looks up the supplied group name and returns a pointer to a struct group (see below), or NULL on an error.

getgrgid() is similar to getgrnam(), except that instead of looking up group information based on group name, a group ID is passed.

To scan the groups database linearly, start the scan with either setgrent() or setgroupent().  The two functions are identical for pure scanning operations, but have different behavior when mixing scan calls with getgrnam() or getgrgid().

After calling setgrent or setgroupent, the scan is set to the first entry in the database.  getgrent returns a pointer to the current entry and moves the scan to the next entry.  In the event of an error, getgrent returns NULL.  When the program is done with the database, endgrent should be called.

If getgrnam or getgrgid is called while scanning the group database, the database will be closed unless it was opened by calling setgroupent with an argument of 1.  This indicates "keep open" mode, and allows fast random access of the database with the getgrnam and getgrgid functions (which would otherwise open and close the database for every call).

getopt  getopt_restart

#include <getopt.h>
int getopt(int argc, char * const *argv, const char *optstring)
int getopt_restart(void)
extern char *optarg;
extern int optind;

Getopt helps parse command line options as are often used by UNIX utilities. It handles simple flags (such as "ls -l") and also flags with arguments ("cc -o prog prog.c").

Getopt returns the next option letter in argv that matches a letter in optstring.  Optstring is a string of recognized option letters; if a letter is followed by a colon, the option is expected to have an argument that  may or may not be separated from it by white space.  Optarg is set to point to the start of the option argument on return from getopt.

Getopt places in optind the argv index of the next argument to be processed.  Because optind is external, it is normally initialized to zero automatically before the first call to getopt.

When all options have been processed (i.e., up to the first  non-option argument), getopt returns EOF. The special option -- may be used to delimit the end of the options; EOF will be returned, and -- will be skipped.

Getopt prints an error message on stderr and returns a question mark (?) when  it encounters an option letter not included in optstring.

The following code fragment shows how one might process the arguments for a command that can take the mutually exclusive options a and b, and the options f and o, both of which require arguments:

	  main(int argc, char **argv)
	  {
	       int c;
	       extern int optind;
	       extern char *optarg;

	       while ((c = getopt(argc, argv, "abf:o:")) != EOF)
		    switch (c) {
		    case `a':
			 if (bflg)
			      errflg++;
			 else
			      aflg++;
			 break;
		    case `b':
			 if (aflg)
			      errflg++;
			 else
			      bproc();
			 break;
		    case `f':
			 ifile = optarg;
			 break;
		    case `o':
			 ofile = optarg;
			 break;
		    case `?':
		    default:
			 errflg++;
			 break;
		    }
	       if (errflg) {
		    fprintf(stderr, "Usage: ...");
		    exit(2);
	       }
	       for (; optind < argc; optind++) {
		    .
              }
	       .
	  }

It is not obvious how `-' standing alone should be treated; this version treats it as a non-option argument, which is not always right.  Option arguments are allowed to begin with `-'; this is reasonable but reduces the amount of error checking possible.

getopt_restart should be used in restartable programs, before the first call to getopt, to reinitialize the optind and optarg variables.

getpass

char *getpass(const char *prompt)
BSD

Prompts the user for a password, and returns a pointer to a NUL-terminated string which contains the password the user typed. A password may be up to 8 characters long, and if the string the user
types is longer than that the returned string is truncated to 8 characters. Argument prompt is the string to print before requesting input. Input characters are obscured - that is, not echoed - as the user types them. The backspace and delete keys may be used to edit input, although in practice this is difficult to use because the user cannot see what he types.

A static buffer is used to to hold the password, so to be sure the password is not overwritten by a subsequent call to getpass, copy it before use.
See also: crypt, getpwent

getpwnam  getpwuid  endpwent  setpwent

#include <pwd.h>
struct passwd *getpwnam(const char *name);
struct passwd *getpwuid(uid_t uid);
void endpwent(void);
struct passwd *getpwent(void);
int setpwent(void);

The family of functions defined in <pwd.h> are used for accessing the /etc/passwd user database.  Programs should never access this database directly, as the file format or other implementation details may change in the future.

getpwnam() reads the user database based on user name.  The argument name is a pointer to the user name to lookup.  getpwnam() returns a pointer to a passwd structure or NULL on an error.

getpwuid() reads the user database based on a user ID code.  Argument uid is the user ID to return information on.  getpwuid() returns a pointer to a passwd structure or NULL on an error.

The remaining three functions are used for scanning the user database. The database is initialized by using the setpwent() function; an internal access marker is set to the first entry in the database.

getpwent() is used to retrieve the current entry, returning a pointer to a passwd structure, and moving the marker to the next entry. If there are no more entries to scan, getpwent() returns a NULL pointer.  If the database should be scanned again, setpwent() may be called again to reset the marker to the first entry.  In the event of an error accessing the database, NULL is returned.

When the application is through with the database, it should call endpwent().

struct	passwd { /* see getpwent(3) */
	char	*pw_name;		/* pointer to user name */
	char	*pw_passwd;		/* pointer to encrypted password */
	int	pw_uid;		/* user ID */
	int	pw_gid;		/* group ID */
	int	pw_quota;		/* 'quota' field - not used */
	char	*pw_comment;	/* pointer Comment field */
	char	*pw_gecos;		/* not used */
	char	*pw_dir;		/* pointer to user's '$home' directory name */
	char	*pw_shell;		/* pointer to path of user's login shell */
};

Not all of the string entries in struct passwd are used in GNO/ME, but those that are are all NUL- terminated strings.

getwd

#include <unistd.h>
char *getwd(char *pathname)

Gets the current working directory (GS/OS prefix 0) and copies it to the string space pointed to by pathname.  pathname must point to a buffer large enough to hold the largest conceivable pathname.  In practice, a 256 byte buffer works well, but with the plethora of GS/OS file systems now available 256 may be much too small.  Due to this problem, we recommend you use getwd carefully, and with a future GNO release switch to getcwd (not yet available).
If an error occurs during the operation, getwd returns NULL and places the error code in errno.  Otherwise, getwd returns the prefix in pathname.

gtty stty

#include <sgtty.h>
int gtty(int filedes, struct sgttyb *argp)
int stty(int filedes, struct sgttyb *argp)

Set and get TTY status information in the sgttyb structures pointed to by the argument argp.  See ioctl(2) and tty(4) for more details.  These routines are basically short-cuts to 
ioctl(filedes, TIOCSETP, &structure) and ioctl(filedes, TIOCGETP, &structure).

index  rindex

char *index(char *a, int b)
char *rindex(char *a, int b)
(BSD)

These functions are identical to strchr() and strrchr(), respectively. See your C compiler manual for more information.  These functions are provided only for compatibility with BSD source code.

isatty

#include <sgtty.h>
int isatty(int filedes)

This function returns true (1) if the file descriptor refers to a TTY (this includes PTYs) file.  For all other types of descriptors, false (0) is returned.

login

#include <utmp.h>
void login(struct utmp *ut)

Writes the /etc/utmp structure pointed to by ut to the utmp file.  The slot in /etc/utmp actually written to depends on the return value of the ttyslot() function, which maps each tty device to a unique slot number, based on the contents of /etc/ttys.

This function should not generally be used by application code.

mkdir

int mkdir(char *dirname)

Creates a subdirectory (folder) with the name specified by dirname.  Similar to the shell 'mkdir' command.

mktemp  mkstemp

char *mktemp(char *path)
int mkstemp(char *path)

Creates a filename based on the string path that is guaranteed to be unique.  The string path must have the following format:

"/volume/dir1/.../dirX/fileXXXXXX"  (Colons are also accepted as delimiters)

The 'XXXXX' at the end of path is filler space that will be replaced with a string that will make path a unique filename.

The unique string is generated by using the current process ID and  a single character ASCII value; this may change in the future, and as such this behavior should not be relied upon.

mktemp() does not actually create any files, as compared with tmpfile() in the C library.

mkstemp() does create a file by calling open() on a unique pathname generated with mktemp().

mktemp() returns a pointer to the new pathname (path), and mkstemp() returns a file descriptor to the new file, as would be returned by open().

open creat close read write lseek

#include <fcntl.h>
int creat(const char *path, int mode)
int open(const char *path, int oflag, ...)
int close(int filds)
int read(int filds, void *buf, size_t count)
int write(int filds, void *buf, size_t count)
long lseek(int filds, long offset, int whence)

These are similar to the low-level I/O routines provided by ORCA/C.  However, the GNO versions of these routines deal with actual GS/OS refNums for filds. (ORCA/C's versions use a special library-maintained definition of file descriptor in order to fake the UNIX dup() system call.  Here they revert to standard UNIX usage because GNO provides a real dup(2) handled within the kernel).

open() uses vararg (variable argument) parameters.  The third parameter is only expected (and is required) if O_CREAT is one of the flags specified in 'mode', and specifies the access permissions to be given the new file.

IMPORTANT NOTE: GNO's read()/write() functions take a size_t count, whereas ORCA's only take unsigned count.  When recompiling code with the new GNO libraries, make very certain that any programs that use read()/write() do a #include <fcntl.h>, or it is likely that your programs will crash.

opendir  readdir  rewinddir  closedir

#include <dirent.h>
DIR *opendir(char *filename)
struct dirent *readdir(DIR *dirp)
void rewinddir(DIR *dirp)
closedir(DIR *dirp)
(POSIX 1)

This family of functions provides a machine-independent way to read a list of files (and information about them) from directories.

opendir() opens the directory specified by filename and prepares it for the scan operation.  opendir() returns a pointer to a structure which is used in the other dirent calls.

readdir() takes a DIR * as argument and returns information about the next file in the directory.  The return value is a pointer to a dirent structure (described below).

If you wish to scan the directory again without closing and then reopening the directory, use rewinddir().  It resets the scan to the beginning of the directory.

When finished with the directory, call closedir().

#define MAXNAMLEN 32	 /* maximum filename length */

struct dirent		 /* data from getdents()/readdir() */
{
        long            d_ino;	 /* inode number of entry */
        off_t           d_off;	 /* offset of disk directory entry */
        unsigned short  d_reclen;	 /* length of this record */
        char    d_name[MAXNAMLEN];	 /* name of file */
        unsigned short  d_namlen;	/* length of filename */
};

dirent is the structure returned by readdir() that contains information about the file.  d_ino is not used on the Apple IIGS because neither ProDOS nor HFS have the concept of an "inode", but to simulate its use a unique d_ino value is returned for each readdir() call. d_off is the offset in the directory of the current file; the first entry is number 1, the second 2, etc.  d_reclen specifies the length of the entire dirent structure. d_name is a short array containing the filename of the current file read from the directory.  d_namlen is the length of the string in d_name.

More specific information can be obtained by passing d_name to the stat() system call.
See also: stat(2)

needsgno

int needsgno(void)

This function returns 1 if GNO is operating, and 0 if it is not.  Use this function to abort programs that use GNO-specific features, or to allow them to enable non-GNO environment dependent code.

parsearg

~GNO_PARSEARG subroutine (4:commandline,4:argptr)
~GNO_PARSEARG(char *commandline, char **argptr)

This function will take the command-line passed to a utility and parse it into an argv,argc structure like those used in C programs. This was written NOT as a replacement for a C parser, but for use by assembly language programmers writing shell commands.

commandline is the raw command line string as passed by the shell in the X & Y registers.  argptr is a pointer to an argv[]-style array. parsearg returns the number of arguments found in the accumulator.

This function ASSUMES that the ByteWorks Memory Manager has been started up and is usable.

This function is based on actual GNO/ME shell (gsh) parsing code.

pcreate pbind pgetport psend preceive pdelete preset pgetcount

#include <sys/ports.h>
int pcreate(int count)
int pbind(int portid, char *name)
int pgetport(char *name)
int psend(int portid, long int msg)
long preceive(int portid)
int pdelete(int portid, int (*dispose)())
int preset(int portid, int (*dispose)())
int pgetcount(int portid)

The Ports IPC mechanism is a very flexible, powerful and efficient method of interprocess communication. A port is a queue that can contain a number of 32-bit values.  The size of the port (how many messages it can contain) is specified in the pcreate() call.

Creation of a port is done with pcreate().  You must specify the size of the port in this call, which must be at least 1 (one).  The larger the port, the more data it can hold without blocking a process sending data to the port. pcreate() returns a port ID value that must be used in subsequent calls to the Port IPC routines.

A name may be associated with a port; this allows totally unrelated processes to access a port without having to communicate the port ID through some other method, and without knowing the process ID of the other.  To bind a name to a port, call pbind().  The name argument may be any length, but at most 32 characters are significant.  If a name has already been bound to the chosen portid, an error is returned.  To get the portid of a port by its name, use the pgetport() call.  Pass in the name of the port whose port ID you wish to obtain.  If no port has that name, an error is returned.  Names are only unbound from a port when a port is deleted.

psend() is used to send a 32-bit datum to a port.  If the port is full (that is, if there are more unread messages in the port than are specified in the pcreate() call) then the sending process blocks until a message is read from the port.  Messages are retrieved from a port using the preceive() call.  pgetcount() returns the number of messages in the port that have not been received; this may be used to avoid blocking on a psend() call.

If you wish to clear the contents of a port, say to synchronize communication after an error condition, use the preset() call.  The arguments to this call are the port ID and the address of a 'dispose' function.  Each message in the port, before being cleared, is passed to the dispose function so that appropriate clean-up action may be taken on the data.  For example, if the messages correspond to the address of memory blocks obtained with malloc(), you could pass 'free()' as the dispose function to automatically deallocate that memory.  If you don't wish to take any special action on the data being cleared, pass NULL for the dispose argument.

To destroy a port, make the pdelete() call.  It accepts the same arguments as preset() and they operate as described above.  The difference between preset() and pdelete() is that the latter totally destroys a port; it may no longer be used.  preset() clears a port's data but leaves the port open for more data transmission.

For an example of the use of ports, see the source code to the print spooling utilities (lpr, lpd, FilePort). These are available from Procyon upon request.

regexp

Compile and execute regular-expression programs.  Use 'man regexp' for details.

send receive recvtim recvclr

#include <gno/gno.h>
int send(int pid, unsigned long msg);
unsigned long receive(void);
unsigned long recvtim(int timeout);
unsigned long recvclr(void);

These kernel functions comprise GNO's message-passing IPC system. Messages are unsigned 32-bit data values.  A process sends a message to another by using the send() call.  You must specify the process ID of the recipient and the message to pass.  To receive a message, a process makes the receive() call.  If no message has been sent to the process, the process sleeps until a message arrives.  recvclr() is used to clear any pending message a process may have waiting.  recvtim() is similar to receive() but takes a timeout argument, specified in 1/10ths of a second.  If no message has been received in timeout/10 seconds, recvtim() fails and returns -1.  The message buffer for a process is only one message deep; any attempt to send() a message to a process that already has one queued results in an error.  For an IPC system with a deeper queue, see the Ports IPC section.

A receive() that is interrupted by a signal will abort and return -1, with errno set to EINTR.

setenv  unsetenv

#include <unistd.h>
int setenv(const char *name, const char *value, int rewrite)
void unsetenv(const char *name)

Set the value of the environmental variable name to be value.  If rewrite is set, setenv replaces any current value.  The variable is considered 'exported', according to the shell convention for variables. No errors are possible, and the only return code is 0.

unsetenv removes the environmental variable specified by name from the variable table.  The variable is no longer accessible, and any value that was assigned to that variable is deallocated. No errors are possible, and there is no return value.

statfs

int statfs(char *path, struct statfs *buf)

Returns information on the filesystem that the file path resides on.  The information is placed in a structure pointed to by the input argument buf.  Read statfs(3) for more information.

strdup

#include <string.h>
char *strdup(const char *str)

strdup() creates a copy of the NUL-terminated string pointed to by str. It allocates a piece of memory exactly large enough to hold the string with the malloc() library function.  When you no longer need the copy, dispose of it with free().
See also: strcpy(), malloc(), free()

strsep

#include <string.h>
char *strsep(char **stringp, const char *delim)

Gets a token from string *stringp, where tokens are nonempty strings separated by characters from delim.

strsep writes NULs into *stringp to end tokens.  delim need not remain constant from call to call.  On return, *stringp points past the last NUL written (if there might be further tokens), or is NULL (if there are definitely no more tokens).  If *stringp is NULL, strsep returns NULL.

termcap

The termcap library accesses the /etc/termcap database, which is used to provide terminal- independent support for advanced terminal features, such as various text modes, scrolling regions, cursor movement, and more.  Use 'man termcap' for more details.

ttyname

#include <unistd.h>
char *ttyname(int fd)

Returns the filename of the tty referenced by file descriptor fd. If fd does not refer to a tty file, NULL is returned.  Otherwise, a pointer to the filename (NUL-terminated string) is returned.

tty filenames are in the format ".ttyXX", where XX is a device designator.  When porting existing BSD code, take care to watch for code that depends on the existence of a '/' character in the string, as UNIX tty files are in the form "/dev/ttyXX".

The string pointer returned points to a static buffer, and will be overwritten on any further calls to ttyname. Copy the string if you wish to preserve it.

unlink

int unlink(char *fname)

Causes the link file specified by fname to be removed.  Since GNO/ME does not yet support symbolic or hard file links, this function operates the same as the remove() (or DestroyGS) routine.

NAME
tty - general terminal interface

SYNOPSIS
#include <sgtty.h>

DESCRIPTION
This file documents the special file .tty and the terminal drivers used for user-oriented I/O.

The Controlling Terminal
Every process has associated with it a controlling terminal, which is the terminal the process was invoked from.  In some versions of Unix, the controlling terminal association is responsible for job control; this is not so under GNO.  A process' controlling terminal is inherited from its parent.  By opening the special file .tty, a process can access its controlling terminal.  This is useful where the input and output of a process was redirected and the process wants to be sure of outputting or getting input from the user at the terminal.

A process can remove the association it has with its controlling terminal by opening the file .tty and issuing an

ioctl(f, TIOCNOTTY, 0);

This is often desirable in server processes.

Process Groups
Every terminal has an associated process group.  Any time a signal-generating special character is typed at the terminal, the terminal's process group is sent that signal. Unix systems set process groups using ioctl() calls, but under GNO a new interface method is used; process group assignments are controlled with the JOB CONTROL(2) routines.

Modes
There are four modes in which terminal drivers operate.  These modes control how the driver deals with I/O.

cooked	This is the default mode of the terminal driver.  If an incoming character is one of the special characters defined in sgttyb, tchars, or ltchars, the appropriate action is performed (see below). This mode also allows for input editing, as input is internally buffered line by line, and data is returned to a reading process only when CR is entered.

cbreak	Input is returned on a per-character basis, instead of line by line as in cooked mode.  If no data is available, a read will block the calling process.  If data is available, a number of characters up to but not exceeding the requested number will be returned.  Special characters such as t_intrc are not handled, but are passed on to the caller as data.

raw	Like cbreak mode, except that no input or output processing whatsoever is performed.

Summary of terminal control modes

Due to the colorful history of Unix systems, the data structures used to manipulate terminal modes and settings are separated into four groups.  Future revisions of GNO will implement the POSIX termio interface, which consolidates these structures into one place.

sgtty
The basic ioctls use the structure defined in <sgtty.h>:

struct sgttyb {
	char	sg_ispeed;
	char	sg_ospeed;
	char	sg_erase;
	char	sg_kill;
	short	sg_flags;
};

sg_ispeed and sg_ospeed indicate the baud rates for input and output according to the following table.  Speed changes that do not apply to a particular piece of hardware are ignored (for instance, the console driver does not access a serial port so all baud rate settings are, in effect, impossible).  Also, not all the baud rates supported by a particular device are allowed to be set from this interface.  

These symbolic names for the baud rate settings are defined in <sgtty.h>.

B0		0	(hang up dataphone)
B50		1	50 baud
B75		2	75 baud
B110		3	110 baud
B134		4	134.5 baud
B150		5	150 baud
B300		7	300 baud
B600		8	600 baud
B1200		9	1200 baud
B1800		10	1800 baud
B2400		11	2400 baud
B4800		12	4800 baud
B9600		13	9600 baud
B19200		and
EXTA		14	19200 baud
B38400		and
EXTB		15	38400 baud
B57600	6	57600 baud

The sg_erase and sg_kill fields specify the line-editing erase and kill characters. sg_erase is 0x7F (delete) by default, and sg_kill is not currently used.

sg_flags is a bitmapped value that indicates various state settings for the terminal driver (values are in hex).

EVENP	0x80	Use Even parity (serial devices only)
ODDP		0x40	Use Odd parity (serial devices only)
RAW		0x20	Raw mode: wake up on all characters, 8-bit interface
CRMOD	0x10	Map CR into LF; output LF as CR-LF
ECHO		0x08	Echo (full duplex)
CBREAK	0x02	Return each character as soon as typed
TANDEM	0x01	Automatic flow control

RAW and CBREAK modes were described above, in Modes.

If the CRMOD bit is set, a line feed character is appended to any echoed or ouputted carriage return.

The ECHO bit controls input echoing; if enabled, any characters read from the terminal are echoed.  This behavior differs slightly from Unix, where input characters are echoed as soon as typed.

TANDEM mode enables automatic software flow control utilizing the special characters t_startc and t_stopc in tchars (below).  Whenever the input queue is in danger of overflowing, the system sends t_stopc; when the queue has drained sufficiently, t_startc is sent.  This mode has no effect on the console driver.

Note: t_startc and t_stopc are used for both directions of flow control; when t_stopc is received from a remote system (or user), the terminal stops output, and when t_startc is received output resumes.  Certain drivers may also require t_stopc and t_startc to be the same character, in which case one or the other setting will be ignored.  See the driver's documentation for details.
Basic Ioctls

Most ioctl() calls apply to terminals.  They have the form
#include <sgtty.h>

ioctl(int filedes, unsigned long code, void *arg)

arg is usually a pointer to a structure or int.  The ioctl codes that apply to sgtty are:

TIOCGETP	Fetch the basic parameters associated with the terminal, and store in the sgttyb structure pointed to by arg.

TIOCSETP	Set the terminal's basic parameters according to the sgttyb structure pointed to by arg.  The input queue is flushed, and the call waits for the output queue to drain before the parameters are changed.

TIOCSETN	This is like TIOCSETP, except there is no delay and the input queue is not flushed.

With the following codes arg is ignored.

TIOCEXCL	Set "exclusive-use" mode.  The terminal may not be opened again by any process until all existing references are closed.

TIOCNXCL	Turns off "exclusive-use" mode.

TIOCHPCL	When the last reference to the terminal is closed, the terminal line is forced to hang up.  This applies only to modem drivers.

With the following codes, arg is a pointer to an int.

TIOCGETD	The current line discipline number is stored in the int pointed to by arg.  This value is currently ignored.

TIOCSETD	The line discipline is set according to the int pointed to by arg.

TIOCFLUSH	The specified queue is flushed.  If the value pointed to by arg is zero, both the input and output queues are flushed.  If the value is FREAD (defined in <sys/file.h>), the input queue is flushed.  If the value is FWRITE, the output queue is flushed.

The last few calls permit detailed control of the driver.  In cases where an argument is required, it is described.  Otherwise, arg should be a NULL pointer.

TIOCSTI	The character pointed to by the argument is placed in the input queue as if it had been typed on the terminal.

TIOCSBRK	Begins a break sequence on the terminal.

TIOCCBRK	Ends a break sequence.

TIOCSDTR	The DTR line is turned on

TIOCCDTR	The DTR line is turned off

TIOCSTOP	Output is stopped as if t_stopc had been typed on the terminal.

TIOCSTART	If output is stopped, it is resumed as if t_startc had been typed on the terminal.

TIOCOUTQ	The number of characters in the output queue is returned in the int pointed to by arg.

FIONREAD	The number of characters immediately available for input from the terminal is returned in the int pointed to by arg.  This is the preferred method of non-blocking I/O (checking for the presence of characters without waiting for them).

Tchars
The second structure associated with a terminal defines special characters. The structure is defined in <sys/ioctl.h> which is automatically included by <sgtty.h>.

struct tchars {
	char	t_intrc;	/* interrupt */
	char	t_quitc;	/* quit */
	char	t_startc;	/* start output */
	char	t_stopc;	/* stop output */
	char	t_eofc;	/* end-of-file */
	char	t_brkc;	/* input delimiter (like nl) */
};

The default values for these characters are ^C, ^\, ^Q, ^S, ^D and -1 respectively.  A value of -1 for any of the characters means that the effect of that character is ignored.  The stop and start characters may be the same to produce a 'toggle' effect.  It is not recommended to set any of the other characters to the same values; the order in which the special characters are checked is not defined, and the results you get may not be what was expected.
The ioctl calls that apply to tchars are:

TIOCGETC	Returns the special characters settings in the tchars structure pointed to by arg.

TIOCSETC	The special characters are set according to the given structure.

Local mode

The third structure in the terminal interface is a local mode word.  The various bitfields in this word are as follows (values are in hex):

LCRTBS	0x0001	Backspace on erase rather than echoing erase
LPRTERA	0x0002	Printing terminal erase mode
LCRTERA	0x0004	Erase character echoes as backspace-space-backspace
LTILDE	0x0008	Convert ~ to ` on output (for Hazeltine terminals)
LMDMBUF	0x0010	Stop/start output when carrier drops
LLITOUT	0x0020	Suppress output translations
LTOSTOP	0x0040	Send SIGTTOU for background output (not implemented)
LFLUSHO	0x0080	Output is being flushed
LNOHANG	0x0100	Don't send hangup when carrier drops
LPASSOUT	0x0200	Cooked mode with 8-bit output
LCRTKIL	0x0400	BS-space-BS erase entire line on line kill
LPASS8	0x0800	Pass all 8 bits through on input, in any mode
LCTLECH	0x1000	Echo input control chars as ^?
LPENDIN	0x2000	Retype pending input at next read or input character
LDECCTQ	0x4000	Only ^Q restarts output after ^S
LNOFLSH	0x8000	Inhibit flushing of pending I/O when intr char is typed

The ioctl's used to access the local mode follow.  arg in all cases is a pointer to an int.

TIOCLBIS	The bits of the local mode word specified by `1' bits in the argument are set; this operation is a bit-wise OR.

TIOCLBIC	The bits of the local mode word specified by `1' bits in the argument are cleared; this operation ANDs the local mode with the bitwise negation of the argument.

TIOCLSET	Sets the local mode word to the value of the argument.

TIOCLGET	Returns the local mode word in the int pointed to by arg.

Local Special Characters
The fourth terminal structure is another set of special characters.  The structure is named ltchars and is again defined in <ioctl.h>.

struct ltchars {
	char	t_suspc;	/* stop process signal */
	char	t_dsuspc;	/* delayed stop process signal */
	char	t_rprntc;	/* reprint line */
	char	t_flushc;	/* flush output (toggles) */
	char	t_werasc;	/* word erase */
	char	t_lnextc;	/* literal next character */
};

Defaults for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V.  As with tchars, a value of -1 disables the effect of that character.  Only t_suspc is currently implemented for the console driver.

The applicable ioctl functions are:

TIOCSLTC	sets the local characters according to the ltchars structure pointed to by arg.

TIOCGLTC	retreives the local characters, storing them in the argument.

Window/terminal sizes

Provision is made for storage of the current window or terminal size along with the other terminal information.  This info is recorded in a winsize structure, and is defined in <ioctl.h>:

struct winsize {
	unsigned short	ws_row;	/* rows, in characters */
	unsigned short	ws_col;	/* columns, in characters */
	unsigned short	ws_xpixel;	/* horizontal size, pixels */
	unsigned short	ws_ypixel;	/* vertical size, pixels */
};

A '0' in a field indicates that the field value is undefined.  '0' is the default when a terminal is first opened.  These values are not used by the terminal driver itself; rather, they are for the benefit of applications.  The ioctl calls for winsize are:

TIOCGWINSZ	Returns the window size parameters in the provided winsize structure.

TIOCSWINSZ	Sets the window size parameters.  If any of the values differ from the old ones, a SIGWINCH signal is sent to the terminal's process group.

FILES
.tty
.ttyco (console driver)
.tty* (user-installed drivers)

SEE ALSO
GNO Shell Reference Manual, stty(1), ioctl(2), signal(2)