initial checkin of man pages

This commit is contained in:
gdr 1997-02-27 07:32:31 +00:00
parent dde31d4227
commit a0b2bf9a39
122 changed files with 16025 additions and 71 deletions

78
usr.man/man1/intro.1 Normal file
View File

@ -0,0 +1,78 @@
.\"
.\" Devin Reade, January 1997
.\"
.\" $Id: intro.1,v 1.1 1997/02/27 07:32:10 gdr Exp $
.\"
.TH INTRO 1 "12 January 1997" GNO "Commands and Applications"
.SH NAME
Intro \- Introduction the manual pages, commands and applications
.SH DESCRIPTION
These are the manual pages for GNO/ME v2.0.6, the multitasking UNIX-like
environment for the Apple IIgs. They are broken up into the following
chapters or sections:
.RS
.nf
1 Commands and Applications
2 System Calls
3 Library Routines
3F Fortran Routines
4 Devices
5 File Formats
6 Games
7 Miscellaneous
8 System Administration
.fi
.RE
Within each chapter, the manual pages are sorted alphabetically.
Chapter
.BR 3F ,
.IR "Fortran Routines" ,
is not currently used, but that chapter is reserved for Fortran routines
(intrinsic and external).
.LP
This page is the introduction to Chapter 1,
.IR "Commands and Applications" .
It covers all external user commands. It specifically excludes shell built-in
commands, games, and programs intended for system administration.
.LP
For third party programs, it is the responsibility of the application
programmer to provide suitable manual pages.
.SH "COMMAND SYNTAX"
Unless otherwise noted, commands described in the
.BR SYNOPSIS
section of a manual page accept options and other arguments
according to the following syntax and should be interpreted as explained
below:
.RS
.sp 1
.BR name
[ \fB-option\fR [ \fIoptarg\fR ] ... ] [ \fIarg\fR ... ]
.sp 1
.RE
where:
.RS
.IP \fBname\fR
is the name of the executable file.
.IP \fB-option\fR
is a single character option flag, almost always preceeded by a hyphen.
Programs which make use of the GNU
.BR getopt (3)
package may also use long options, which are multi-character options
preceeded by two hypens (such as
.BR --recursive .)
.IP \fIoptarg\fR
is the option argument, if required.
.IP \fIarg\fR
is a regular argument, if required.
.IP "[ ]"
Surround an
.BR option
or
.IR argument
that is optional.
.IP "..."
indicate multiple occurances of the preceeding symbol.
.SH "SEE ALSO"
.I "GNO Shell User's Manual"

165
usr.man/man2/accept.2 Normal file
View File

@ -0,0 +1,165 @@
.\" Copyright (c) 1983, 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)accept.2 8.2 (Berkeley) 12/11/93
.\"
.TH ACCEPT 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR accept
\- accept a connection on a socket
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBaccept\fR (int \fIs\fR, struct sockaddr *\fIaddr\fR, int *\fIaddrlen\fR);
.SH DESCRIPTION
The argument
.I s
is a socket that has been created with
.BR socket (2),
bound to an address with
.BR bind (2),
and is listening for connections after a
.BR listen (2).
The
.BR accept
argument
extracts the first connection request
on the queue of pending connections, creates
a new socket with the same properties of
.I s
and allocates a new file descriptor
for the socket. If no pending connections are
present on the queue, and the socket is not marked
as non-blocking,
.BR accept
blocks the caller until a connection is present.
If the socket is marked non-blocking and no pending
connections are present on the queue,
.BR accept
returns an error as described below.
The accepted socket
may not be used
to accept more connections. The original socket
.I s
remains open.
.LP
The argument
.I addr
is a result parameter that is filled in with
the address of the connecting entity,
as known to the communications layer.
The exact format of the
.I addr
parameter is determined by the domain in which the communication
is occurring.
The
.I addrlen
is a value-result parameter; it should initially contain the
amount of space pointed to by
.IR addr ,
on return it will contain the actual length (in bytes) of the
address returned.
This call
is used with connection-based socket types, currently with
.BR SOCK_STREAM .
.LP
It is possible to
.BR select (2)
a socket for the purposes of doing an
.BR accept
by selecting it for read.
.LP
For certain protocols which require an explicit confirmation,
such as
ISO or DATAKIT,
.BR accept
can be thought of
as merely dequeueing the next connection
request and not implying confirmation.
Confirmation can be implied by a normal read or write on the new
file descriptor, and rejection can be implied by closing the
new socket.
.LP
One can obtain user connection request data without confirming
the connection by issuing a
.BR recvmsg (2)
call with an
.I msg_iovlen
of 0 and a non-zero
.IR msg_controllen ,
or by issuing a
.BR getsockopt (2)
request.
Similarly, one can provide user connection rejection information
by issuing a
.BR sendmsg (2)
call with providing only the control information,
or by calling
.BR setsockopt (2).
.SH RETURN VALUES
The call returns \-1 on error. If it succeeds, it returns a non-negative
integer that is a descriptor for the accepted socket.
.SH ERRORS
The
.BR accept
will fail if:
.RS
.IP \fBEBADF\fR
The descriptor is invalid.
.IP \fBENOTSOCK\fR
The descriptor references a file, not a socket.
.IP \fBEOPNOTSUPP\fR
The referenced socket is not of type
.BR SOCK_STREAM .
.IP \fBEFAULT\fR
The
.I addr
parameter is not in a writable part of the
user address space.
.IP \fBEWOULDBLOCK\fR
The socket is marked non-blocking and no connections
are present to be accepted.
.RE
.SH SEE ALSO
.BR bind (2),
.BR connect (2),
.BR listen (2),
.BR select (2),
.BR socket (2)
.SH HISTORY
The
.BR accept
function appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

91
usr.man/man2/access.2 Normal file
View File

@ -0,0 +1,91 @@
.\"
.\" Devin Reade, 1995
.\"
.\" $Id: access.2,v 1.1 1997/02/27 07:32:11 gdr Exp $
.\"
.TH ACCESS 2 "16 January 1997" GNO "System Calls"
.SH NAME
access \- determine accessibility of file
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBaccess\fR (const char *\fIpath\fR, int \fImode\fR);
.SH DESCRIPTION
.I path
points to a path name naming a file.
.B access(\|)
checks the named file
for accessibility according to
.IR mode ,
which is an inclusive or of the following bits:
.RS
.IP \fBR_OK\fR
Test for read permission.
.IP \fBW_OK\fR
Test for write permission. Under GNO, a file must have all three of
its GS/OS write, rename, and destroy bits set to be considered writable.
.IP \fBX_OK\fR
Test for execute or search permission. Under GNO, the test will pass if
the file is of type EXE, S16, a directory, or of type SRC with an EXEC
auxiliary type.
.RE
.LP
The following value may also be supplied for
.IR mode :
.RS
.IP \fBF_OK\fR
test whether the directories leading to the file can be searched and the file exists.
.RE
.LP
Notice that only access bits are checked. A directory may be indicated as writable by
.BR access(\|) ,
but an attempt to open it for writing will fail
(although files may be created there); a file may look executable, but
.B execve(\|)
will fail unless it is in proper format.
.SH RETURN VALUES
.B access(\|)
returns zero on success. On failure it returns -1 and sets
.BR errno .
.SH ERRORS
.IP EACCES
Search permission is denied for a component of the path prefix of
.IR path .
.sp 1
The file access permissions do not permit the requested
access to the file named by
.IR path .
.IP EFAULT
.I path
points outside the process's allocated address space.
.IP EINVAL
An invalid value was specified for
.IR mode .
.sp 1
The length of the path argument exceeds
.BR FILENAME_MAX .
.IP EIO
An I/O error occurred while reading from or writing to the file system.
.IP ELOOP
Too many symbolic links were encountered in translating
.IR path .
(Not currently possible under GNO.)
.IP ENOENT
The file named by
.I path
does not exist.
.IP ENOTDIR
A component of the path prefix of
.I path
is not a directory.
.SH SYSTEM V ERRORS
In addtion to the above, the following may also occur:
.IP ENOENT
.I path
points to an empty string.
.SH BUGS
Nothing special is done for the AppleShare FST.
.SH "SEE ALSO"
.BR chmod (2V),
.BR stat (2V)

94
usr.man/man2/alarm.2 Normal file
View File

@ -0,0 +1,94 @@
.\" Copyright (c) 1980, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)alarm.3 8.2 (Berkeley) 4/19/94
.\"
.TH ALARM 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR alarm
\- set signal timer alarm
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
long
\fBalarm\fR (long \fIseconds\fR);
.br
long
\fBalarm10\fR (long \fItenths\fR);
.SH DESCRIPTION
.LP
The
.BR alarm
function
waits a count of
.BR seconds
before asserting the terminating signal
.BR SIGALRM .
When the signal has successfully been caught,
.BR alarm
returns the amount of time left on the clock.
.LP
If an alarm has been set with
.BR alarm ,
another call to
.BR alarm
will supersede the prior call.
If
.IR seconds
is zero, the alarm timer is disabled.
.LP
.BR alarm10
is identical to
.BR alarm ,
except that values are measured in tenths of seconds.
.SH ERRORS
No errors are possible.
.SH STANDARDS
.BR alarm
is not quite POSIX conformant in that it uses types of
.BR long
rather than
.BR "unsigned int" .
.BR alarm10
is a non-standard function.
.SH SEE ALSO
.BR setitimer (2),
.BR sigpause (2),
.BR sigvec (2),
.BR signal (2),
.BR sleep (3),
.BR ualarm (3),
.BR usleep (3)
.SH HISTORY
An
.BR alarm
function appeared in v7.

127
usr.man/man2/bind.2 Normal file
View File

@ -0,0 +1,127 @@
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)bind.2 8.1 (Berkeley) 6/4/93
.\"
.TH BIND 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR bind
\- bind a name to a socket
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBbind\fR (int \fIs\fR, struct sockaddr *\fIname\fR, int \fInamelen\fR);
.SH DESCRIPTION
.BR Bind
assigns a name to an unnamed socket.
When a socket is created
with
.BR socket (2)
it exists in a name space (address family)
but has no name assigned.
.BR Bind
requests that
.I name
be assigned to the socket.
.SH NOTES
Binding a name in the UNIX domain creates a socket in the file
system that must be deleted by the caller when it is no longer
needed (using
.BR unlink (2)).
.LP
The rules used in name binding vary between communication domains.
Consult the manual entries in section 4 for detailed information.
.SH RETURN VALUES
If the bind is successful, a 0 value is returned.
A return value of -1 indicates an error, which is
further specified in the global
.IR errno .
.SH ERRORS
The
.BR bind
call will fail if:
.RS
.IP \fBEBADF\fR
.I S
is not a valid descriptor.
.IP \fBENOTSOCK\fR
.I S
is not a socket.
.IP \fBEADDRNOTAVAIL\fR
The specified address is not available from the local machine.
.IP \fBEADDRINUSE\fR
The specified address is already in use.
.IP \fBEINVAL\fR
The socket is already bound to an address.
.IP \fBEACCES\fR
The requested address is protected, and the current user
has inadequate permission to access it.
.IP \fBEFAULT\fR
The
.I name
parameter is not in a valid part of the user
address space.
.RE
.LP
The following errors are specific to binding names in the UNIX domain.
.RS
.IP \fBENOTDIR\fR
A component of the path prefix is not a directory.
.IP \fBEINVAL\fR
The pathname contains a character with the high-order bit set.
.IP \fBENAMETOOLONG\fR
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.IP \fBENOENT\fR
A prefix component of the path name does not exist.
.IP \fBELOOP\fR
Too many symbolic links were encountered in translating the pathname.
.IP \fBEIO\fR
An I/O error occurred while making the directory entry or allocating the inode.
.IP \fBEROFS\fR
The name would reside on a read-only file system.
.IP \fBEISDIR\fR
An empty pathname was specified.
.RE
.SH SEE ALSO
.BR connect (2),
.BR listen (2),
.BR socket (2),
.BR getsockname (2)
.SH HISTORY
The
.BR bind
function call appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

110
usr.man/man2/chdir.2 Normal file
View File

@ -0,0 +1,110 @@
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)chdir.2 8.2 (Berkeley) 12/11/93
.\"
.TH CHDIR 2 "26 January 1997" GNO "System Calls"
.SH NAME
.BR chdir ,
.BR fchdir
\- change current working directory
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBchdir\fR (const char *\fIpath\fR);
.br
int
\fBfchdir\fR (int \fIfd\fR);
.SH DESCRIPTION
The
.I path
argument points to the pathname of a directory.
The
.BR chdir
function
causes the named directory
to become the current working directory, that is,
the starting point for path searches of pathnames not beginning with
a slash
.RB ( / ),
a colon
.RB ( : ),
or a device name.
.LP
The
.BR fchdir
function
causes the directory referenced by
.I fd
to become the current working directory,
the starting point for path searches of pathnames not beginning with
a slash
.RB ( / ),
a colon
.RB ( : ),
or a device name.
.LP
Under GNO, these calls are wrappers to the GS/OS
.BR SetPrefix
call. If the length of
.IR path
is equal to or less than 64 characters, both GS/OS prefix 0 (zero)
and 8 will be set. If the length of
.IR path
is over 64 characters, then GS/OS prefix 0 is set to a zero length
string and prefix 8 is set to the value of
.IR path .
.LP
If an error occurs in setting prefix 8 or both prefixes 0 and 8, then neither
prefix will be set and these calls fail. If the setting of prefix 8
succeeds but an error occurs when setting prefix 0, then prefix 0 is set
to a zero length string. In the latter case these calls are considered
to have succeeded.
.LP
In order for a directory to become the current directory,
a process must have execute (search) access to the directory.
.SH RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
.IR errno
is set to indicate
the error.
.SH SEE ALSO
.BR chroot (2)
.SH STANDARDS
.BR chdir
is expected to conform to IEEE Std 1003.1-1988 (POSIX).
.SH HISTORY
The
.BR fchdir
function call
appeared in 4.2BSD.

152
usr.man/man2/chmod.2 Normal file
View File

@ -0,0 +1,152 @@
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93
.\"
.TH CHMOD 2 "22 February 1996" GNO "System Calls"
.SH NAME
.BR chmod ,
.BR fchmod
\- change mode of file
.SH SYNOPSIS
#include <sys/stat.h>
.sp 1
int
\fBchmod\fR (const char *\fIpath\fR, mode_t \fImode\fR);
.br
int
\fBfchmod\fR (int \fIfd\fR, mode_t \fImode\fR);
.SH DESCRIPTION
The function
.BR chmod
sets the file permission bits
of the file
specified by the pathname
.I path
to
.IR mode .
.BR fchmod
sets the permission bits of the specified
file descriptor
.IR fd .
.BR chmod
verifies that the process owner (user) either owns
the file specified by
.I path
(or
.IR fd )
or
is the super-user.
A mode is created from
.IR or'd
permission bit masks
defined in <sys/stat.h>:
.nf
#define S_IRWXU 0000700 /* RWX mask for owner */
#define S_IRUSR 0000400 /* R for owner */
#define S_IWUSR 0000200 /* W for owner */
#define S_IXUSR 0000100 /* X for owner */
#define S_IRWXG 0000070 /* RWX mask for group */
#define S_IRGRP 0000040 /* R for group */
#define S_IWGRP 0000020 /* W for group */
#define S_IXGRP 0000010 /* X for group */
#define S_IRWXO 0000007 /* RWX mask for other */
#define S_IROTH 0000004 /* R for other */
#define S_IWOTH 0000002 /* W for other */
#define S_IXOTH 0000001 /* X for other */
#define S_ISUID 0004000 /* set user id on execution */
#define S_ISGID 0002000 /* set group id on execution */
#define S_ISVTX 0001000 /* save swapped text even after use */
.fi
.LP
The
.BR ISVTX
(the
.IR sticky
bit )
indicates to the system which executable files are shareable (the
default) and the system maintains the program text of the files
in the swap area. The sticky bit may only be set by the super user
on shareable executable files.
.LP
If mode
.BR ISVTX
(the `sticky bit') is set on a directory,
an unprivileged user may not delete or rename
files of other users in that directory. The sticky bit may be
set by any user on a directory which the user owns or has appropriate
permissions.
For more details of the properties of the sticky bit, see
.BR sticky (8).
.LP
Writing or changing the owner of a file
turns off the set-user-id and set-group-id bits
unless the user is the super-user.
This makes the system somewhat more secure
by protecting set-user-id (set-group-id) files
from remaining set-user-id (set-group-id) if they are modified,
at the expense of a degree of compatibility.
.SH COMPATIBILITY
The Orca/C implementation of
.BR chmod
interprets
.IR mode
as GS/OS access bits. In order to get this behavior with the GNO
implementation, mode mapping must be turned off (see
.BR mapMode (3)).
.SH RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
.IR errno
is set to indicate the error.
.SH BUGS
Verification of the ownership of the target file is not currently checked
under GNO. (This would matter only for Appleshare volumes.)
.LP
Due to GNO's underlying filesystems, the sticky bit is not implemented.
.SH SEE ALSO
.BR chmod (1),
.BR open (2),
.BR chown (2),
.BR stat (2),
.BR sticky (8)
.SH STANDARDS
.BR chmod
is expected to conform to IEEE Std 1003.1-1988 (POSIX).
.SH HISTORY
The
.BR fchmod
function call
appeared in 4.2BSD.

85
usr.man/man2/close.2 Normal file
View File

@ -0,0 +1,85 @@
.\" Copyright (c) 1980, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)close.2 8.2 (Berkeley) 4/19/94
.\"
.TH CLOSE 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR close
\- delete a descriptor
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBclose\fR(int \fIfd\fR);
.SH DESCRIPTION
The
.BR close
call deletes a descriptor from the per-process file descriptor table.
If this is the last reference to the underlying object, the
object will be deactivated.
For example, on the last close of a file
the current
.IR seek
pointer associated with the file is lost;
on the last close of a
.BR socket (2)
associated naming information and queued data are discarded;
on the last close of a file holding an advisory lock
the lock is released (see further
.BR flock (2)).
.SH RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and the global integer variable
.IR errno
is set to indicate the error.
.SH ERRORS
.BR Close
will fail if:
.RS
.IP \fBEBADF\fR
.I fd
is not an active descriptor.
.IP \fBEINTR\fR
An interrupt was received.
.RE
.SH SEE ALSO
.BR accept (2),
.BR flock (2),
.BR open (2),
.BR pipe (2),
.BR socket (2),
.BR socketpair (2),
.BR execve (2),
.BR fcntl (2)
.SH STANDARDS
.BR close
conforms to IEEE Std 1003.1-1988 (POSIX).

146
usr.man/man2/connect.2 Normal file
View File

@ -0,0 +1,146 @@
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)connect.2 8.1 (Berkeley) 6/4/93
.\"
.TH CONNECT 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR connect
\- initiate a connection on a socket
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBconnect\fR (int \fIs\fR, struct sockaddr *\fIname\fR, int \fInamelen\fR);
.SH DESCRIPTION
The parameter
.I s
is a socket.
If it is of type
.BR SOCK_DGRAM ,
this call specifies the peer with which the socket is to be associated;
this address is that to which datagrams are to be sent,
and the only address from which datagrams are to be received.
If the socket is of type
.BR SOCK_STREAM ,
this call attempts to make a connection to
another socket.
The other socket is specified by
.IR name ,
which is an address in the communications space of the socket.
Each communications space interprets the
.I name
parameter in its own way.
Generally, stream sockets may successfully
.BR connect
only once; datagram sockets may use
.BR connect
multiple times to change their association.
Datagram sockets may dissolve the association
by connecting to an invalid address, such as a null address.
.SH RETURN VALUES
If the connection or binding succeeds, 0 is returned.
Otherwise a -1 is returned, and a more specific error
code is stored in
.IR errno .
.SH ERRORS
The
.BR connect
call fails if:
.RS
.IP \fBEBADF\fR
.I S
is not a valid descriptor.
.IP \fBENOTSOCK\fR
.I S
is a descriptor for a file, not a socket.
.IP \fBEADDRNOTAVAIL\fR
The specified address is not available on this machine.
.IP \fBEAFNOSUPPORT\fR
Addresses in the specified address family cannot be used with this socket.
.IP \fBEISCONN\fR
The socket is already connected.
.IP \fBETIMEDOUT\fR
Connection establishment timed out without establishing a connection.
.IP \fBECONNREFUSED\fR
The attempt to connect was forcefully rejected.
.IP \fBENETUNREACH\fR
The network isn't reachable from this host.
.IP \fBEADDRINUSE\fR
The address is already in use.
.IP \fBEFAULT\fR
The
.I name
parameter specifies an area outside
the process address space.
.IP \fBEINPROGRESS\fR
The socket is non-blocking
and the connection cannot
be completed immediately.
It is possible to
.BR select (2)
for completion by selecting the socket for writing.
.IP \fBEALREADY\fR
The socket is non-blocking
and a previous connection attempt
has not yet been completed.
.RE
.LP
The following errors are specific to connecting names in the UNIX domain.
These errors may not apply in future versions of the UNIX IPC domain.
.RS
.IP \fBENOTDIR\fR
A component of the path prefix is not a directory.
.IP \fBEINVAL\fR
The pathname contains a character with the high-order bit set.
.IP \fBENAMETOOLONG\fR
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.IP \fBENOENT\fR
The named socket does not exist.
.IP \fBEACCES\fR
Search permission is denied for a component of the path prefix.
.IP \fBEACCES\fR
Write access to the named socket is denied.
.IP \fBELOOP\fR
Too many symbolic links were encountered in translating the pathname.
.RE
.SH SEE ALSO
.BR accept (2),
.BR select (2),
.BR socket (2),
.BR getsockname (2)
.SH HISTORY
The
.BR connect
function call appeared in 4.2BSD.

63
usr.man/man2/creat.2 Normal file
View File

@ -0,0 +1,63 @@
.\" Copyright (c) 1989, 1990, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)creat.2 8.1 (Berkeley) 6/2/93
.\"
.TH CREAT 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR creat
\- create a new file
.SH SYNOPSIS
.br
#include <fcntl.h>
.sp 1
int
creat (const char *path, mode_t mode);
.SH DESCRIPTION
This interface is made obsolete by:
.BR open (2).
.BR creat
is the same as:
.nf
open(path, O_CREAT | O_TRUNC | O_WRONLY, mode);
.fi
Note that under GNO,
.BR creat ing
a file with only read permission will fail if that file doesn't already
exist.
.SH SEE ALSO
.BR open (2)
.SH HISTORY
The
.BR creat
function call appeared in Version 6 AT&T UNIX.

129
usr.man/man2/dup.2 Normal file
View File

@ -0,0 +1,129 @@
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)dup.2 8.1 (Berkeley) 6/4/93
.\"
.TH DUP 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR dup ,
.BR dup2
\- duplicate an existing file descriptor
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
int
\fBdup\fR (int \fIoldfd\fR);
.br
int
\fBdup2\fR (int \fIoldfd\fR, int \fInewfd\fR);
.SH DESCRIPTION
.BR Dup
duplicates an existing file descriptor and returns its value to
the calling process.
The argument
.I oldfd
is a small non-negative integer index in
the per-process descriptor table. The value must be less
than the size of the table, which is returned by
.BR getdtablesize (2).
The new descriptor returned by the call
is the lowest numbered descriptor
currently not in use by the process.
.LP
The file referenced by the descriptor does not distinguish
between
.I oldfd
and
.I newfd
in any way.
Thus if
.I newfd
and
.I oldfd
are duplicate references to an open
file,
.BR read (2),
.BR write (2)
and
.BR lseek (2)
calls all move a single pointer into the file,
and append mode, non-blocking I/O and asynchronous I/O options
are shared between the references.
If a separate pointer into the file is desired, a different
reference to the file must be obtained by issuing an
additional
.BR open (2)
call.
The close-on-exec flag on the new file descriptor is unset.
.LP
In
.BR dup2 ,
the value of the new descriptor
.I newfd
is specified. If this descriptor is already
in use, the descriptor is first deallocated as if a
.BR close (2)
call had been done first.
.SH RETURN VALUES
The value -1 is returned if an error occurs in either call.
The external variable
.IR errno
indicates the cause of the error.
.SH ERRORS
.BR Dup
and
.BR dup2
fail if:
.RS
.IP \fBEBADF\fR
.I Oldfd
or
.I newfd
is not a valid active descriptor
.IP \fBEMFILE\fR
Too many descriptors are active.
.RE
.SH SEE ALSO
.BR accept (2),
.BR open (2),
.BR close (2),
.BR fcntl (2),
.BR pipe (2),
.BR socket (2),
.BR socketpair (2),
.BR getdtablesize (2)
.SH STANDARDS
.BR Dup
and
.BR dup2
are expected to conform
to IEEE Std 1003.1-1988 (POSIX).

215
usr.man/man2/execve.2 Normal file
View File

@ -0,0 +1,215 @@
.\" This man page was orginally written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 by Devin Reade. As of GNO v2.0.6 it is now
.\" part of libc.
.\"
.\" $Id: execve.2,v 1.1 1997/02/27 07:32:12 gdr Exp $
.\"
.TH EXECVE 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR execve ,
.BR _execve ,
\- replace current process with an executable image from a file
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fB_execve\fR(const char *\fIpath\fR, const char *\fIcmdline\fR);
.br
int
\fBexecve\fR(const char *\fIpath\fR, char * const *\fIargv\fR,
char * const *\fIenvp\fR);
.SH DESCRIPTION
The
.B exec
family of calls,
.IR not
including
.BR exec (3),
are the preferred
method for loading program files to be executed under the GNO system.
This manual page describes
.BR execve (2)
and
.BR _execve (2).
(See the section on HISTORY, below.)
All other calls in the exec family are implemented in terms of
.BR _execve .
.LP
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.
The executable loaded replaces the executable associated with the
current process.
.I path
can be a partial or complete path. A partial pathname
will suffice only if the file resides in the current directory.
.LP
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).
.LP
The argument
.I argv
is a pointer to a null-terminated array of
character pointers to null-terminated character strings.
These strings construct the argument list to be made available to the new
process (a copy is actually passed). At least one
argument must be present in
the array; by custom, the first element should be the name of the
executed program (for example, the last component of \fIpath\fR).
.LP
The argument
.I envp
is also a pointer to a null-terminated array of
character pointers to null-terminated strings.
A pointer to this array is normally stored in the global variable
.I environ
if
.BR environInit (3)
has been previously called. (If not, then the same
information still resides in the shell's internal variables.)
These strings pass information to the new process that is not directly
an argument to the command (see
.IR environ (7)).
.LP
The parameter
.IR cmdline
is functionally equivalent to
.IR argv ,
but it is implemented as a single string consisting of a list of
whitespace delimited arguments. C programs parse
.IR cmdline
automatically, and the individual pieces can be accessed through
the argc/argv arguments to main().
.LP
.I cmdline
can be accessed from assembly
langugage through the X (high-order word of \fIcmdline\fR) and Y
(low-order word) registers. See
.BR parsearg (3)
for a method of parsing the command line under assembly language.
.LP
If the executable file is of filetype S16 ($B3), the
.IR 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
.BR BYTEWRKS
are prepended to
.I cmdline
before being passed to the process (this is the same identifier used
by 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
.BR shellid (3).
The A register is set to the userID allocated for the process.
.LP
GS/OS prefixes 1 and 9 are set to the pathname of the
directory containing the executable file; if the length of
.IR path
exceeds 64 characters prefix 1 is set to the null prefix (length 0).
The following information is inherited by the child:
.RS
.nf
current machine state;
controlling TTY;
process group ID; and
prefixes 0 and 8.
.fi
.RE
.LP
Caught signals are reset to the default action.
Ignored signals remain ignored across the
.BR 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.
.SH RETURN VALUE
A successful
.BR execve
does not return, as the current executable is replaced with the one
specified in the call. If for some reason the call fails,
.BR execve
returns -1 and sets
.BR errno
to indicate the error.
.SH ERRORS
.IP \fBENOENT\fR
The filename specified does not exist.
.IP \fBENOMEM\fR
Could not allocate necessary memory to build arguments.
.IP \fBEIO\fR
Some general I/O error occurred trying to load the executable.
.SH NOTES
Since all of the exec family calls are implemented using \fI_execve\fR,
if a single string consisting of all arguments is already available then
calling \fI_execve\fR is the most efficient choice. If, however, the
argument list must be constructed, then an appropriate choice of one
of the other exec family functions should be made.
.LP
Use of the \fIexec\fR(3) call is discouraged; this call is provided only
for backward compatibility.
.SH BUGS
.IR execve
is not currently implemented in the kernel; instead it is implemented
as a library routine on top of
.BR _execve .
Consequently, any environment information passed in by
.IR envp
will modify the environment of the parent process as well as that of
the child process. It is possible to use
.BR environPush (3)
in the parent process before the
.BR fork ,
followed by a
.BR environPop (3)
in the parent after child has had a chance to
.BR execve ,
however this is normally a race condition and the result is therefore
indeterminant.
.LP
Programs compiled with Orca/C v1.3 (and earlier) ignore any stack space
allocated by the GS/OS Loader (which
.BR _execve
calls. Stack space in Orca/C programs is determined by code in the
.BR "*.root"
object file, and can be set with the
.BR "#pragma stacksize"
directive. Read the chapter on GNO Compliance in the
.I "GNO Kernel Reference Manual"
for more information on this topic. Orca/C v2.0 and later versions use
the system-provided stack space.
.SH SEE ALSO
.BR exit (2),
.BR fork (2),
.BR ioctl (2),
.BR wait (2),
.BR exec (3),
.BR execl (3),
.BR environInit (3),
.BR environPush (3),
.BR tty (4),
.BR environ (7),
and the
.IR "GNO Kernel Reference Manual" .
.SH HISTORY
The
.B _execve
function call appeared in GNO versions 1.0 through 2.0.4 inclusive
under the name
.BR execve .
.LP
The
.B execve
function call appeared in 4.2BSD.
The first GNO implementation was part of the
.BR lenviron
library by Devin Reade, written for GNO v2.0.3.
.LP
These implementations of
.BR _execve
and
.BR execve
became part of the GNO distribution as of v2.0.6.

215
usr.man/man2/fork.2 Normal file
View File

@ -0,0 +1,215 @@
.\"
.\" Devin Reade, 1997
.\"
.\" $Id: fork.2,v 1.1 1997/02/27 07:32:12 gdr Exp $
.\"
.\" .TH FORK2 2 GNO "System Calls" "16 December 1996"
.TH FORK 2 GNO "16 January 1997" "System Calls"
.SH NAME
.BR fork ,
.BR fork2 ,
.BR vfork
\- start a new process from inside the current application space
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBfork\fR (void *\fIproc\fR);
.br
int
\fBvfork\fR (void *\fIproc\fR);
.br
int
\fBfork2\fR (void *\fIproc\fR, unsigned short \fIstack\fR,
unsigned short \fIprio\fR, char *\fIprocname\fR,
unsigned short \fInumargs\fR, ...);
.SH DESCRIPTION
.BR fork
causes the creation of a new process.
.LP
.BR fork 's
argument
.IR proc
is typically the address of a C function, although it can be any valid
address inside the IIgs RAM space. In a successful
.BR fork
call, the parent process resumes execution by returning from
.BR fork
and, under GNO, the child process resumes execution at the entry into function
.IR proc .
This is different from traditional Unix implementations.
.LP
.BR 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:
.RS
.nf
A the userID assigned to the new process
X 0
Y 0
.fi
.RE
.LP
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.
.LP
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
.BR semaphore (2)
routines or custom routines. This includes C stdio routines.
.LP
There is no way to pass parameters directly to a child with
.BR fork .
Use
.BR fork2
instead.
.LP
Under GNO,
.BR vfork
is identical to
.BR fork ;
other than the
.IR proc
parameter (and therefore the point at which the child process resumes
execution),
.BR vfork
is the same as the BSD implementation in that the two processes
share an address space.
.LP
.B fork2
is similar to
.BR fork (2),
except that it allows parameters to be passed both to
.IR proc
and the execution environment:
.RS
.IP \fIstack\fR
is the number of bytes of stack to allocate to the proess. If
.I stack
is not a multiple of 256, then it
is rounded up to the next highest multiple of 256 bytes.
.IP \fIprio\fR
is the priority to assign to the process. Priorities are not currently
implemented, and you should pass 0 for this argument.
.IP \fIprocname\fR
is a string you can have associated with the process when viewing
the process table (See
.BR ps (1)).
.IP \fInumargs\fR
is the number of (16-bit)
.B words
of arguments which follow, not the
number of arguments.
Any arguments following
.I numargs
are passed as parameters to the child's procedure.
.RE
See below for an example of the use of
.BR fork2 .
.SH "RETURN VALUE"
On success
.BR fork ,
.BR vfork ,
and
.BR fork2
return to the parent the process ID of the new (child) process.
On failure, -1 is returned and
.B errno
is set.
.SH CAVEATS
Care must be taken such that the child process does not call
.BR exit (3)
either directly or by function call, since
.BR exit
will flush and close standard I/O data structures. Instead, if
the child process does not or cannot
.BR execve (2),
it should call
.BR _exit (3).
.LP
Orca/C's stack checking and stack repair code should be turned off
when compiling routines containing these functions. See
.BR occ (1)
or the Orca/C Reference Manual for details.
.LP
Because the
.BR fork
functions are called from the kernel (which is implemented as a user
tool set), the child function
.IR proc
must restore the data bank register if it is going to access global
variables. See the description of the
.BR databank
pragma in the Orca/C Reference Manual for details.
.LP
While
.BR Splat!
is an excellent source level debugger, it is (at the time of this
writing) unable to handle the execution of
.BR fork ,
.BR fork2 ,
or
.BR vfork
calls. If you attempt to do so, your machine will almost certainly
crash. Otherwise,
.BR Splat!
is strongly recommended as a powerful tool for GNO programmers using
C as their source language. (For the record, the author of this manual
page receives no renumeration from the sales of
.BR Splat! )
.SH CONFORMANCE
Most Unix
.BR fork s
take no parameters; they copy the entire address space of the calling
process and return witha different value in the parent and child. Due
to hardware limitations, this sort of manipulation isn't possible on
the IIgs. Unix programs utilizing
.BR fork
will have to be modified slightly to work under GNO.
.LP
The implementation of
.BR fork
is therefore not POSIX conforming, nor is the implementation of
.BR vfork
conforming to traditional Unix implementations.
.SH EXAMPLE
.nf
int main (int argc, char **argv) {
...
pid = fork2(proc1,1024,0,"sub-process",3,argc,argv);
...
return 0;
}
void proc1(int argc, char *argv[])
{
...
}
.fi
.SH HISTORY
.B fork2
first appeared in XINU.
.LP
.B vfork
first appeared in 3.0BSD.
.SH "SEE ALSO"
.BR occ (1),
.BR exec (2),
.BR execve (2),
.BR semaphore (2),
.BR wait (2),
the
.IR "GNO Kernel Reference Manual" ,
and the
.IR "Orca/C Reference Manual" .

View File

@ -1,71 +0,0 @@
.TH FORK2 2
.SH NAME
fork2 \- start a new process from inside the current application
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
.BR fork2