Apple-2gs-SW
/
gno
mirror of https://github.com/GnoConsortium/gno.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

71
usr.man/man2/fork2.2
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
.RI " (void *" proc ,
word
.IR stack ,
word
.IR prio ", char *" procname ,
word
.IR numargs ", ...);"
.SH DESCRIPTION
.B fork2
is similar to
.BR fork (2),
except that it allows more parameters to be passed than just function
which the child process will execute.
.LP
.I proc
is the name of the function at which the child process will begin execution.
.I stack
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.
.I prio
is the priority to assign to the process. Priorities are not currently
implemented, and you should pass 0 for this argument.
.I procname
is a string you can have associated with the process when viewing
the process table (See
.BR ps (1)).
.I numargs
is the number of
.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.
.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 "RETURN VALUE"
.BR fork2
returns to the parent the process ID of the new process on success.
On failure, -1 is returned and
.B errno
is set.
.SH HISTORY
.B fork2
first appeared in XINU.

86
usr.man/man2/fsync.2 Normal file
View File

@ -0,0 +1,86 @@
.\" 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.
.\"
.\" @(#)fsync.2 8.1 (Berkeley) 6/4/93
.\"
.TH FSYNC 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR fsync
\- synchronize a file
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBfsync\fR (int \fIfd\fR);
.SH DESCRIPTION
.BR fsync
causes all modified data and attributes of
.I fd
to be moved to a permanent storage device.
This normally results in all in-core modified copies
of buffers for the associated file to be written to a disk.
.LP
.BR fsync
should be used by programs that require a file to be
in a known state, for example, in building a simple transaction
facility.
.LP
This call is only needed in special circumstances, as when several
daemons are all modifying the same file simultaneously (currently
impossible with existing IIgs filesystems). This call is basically a
.BR FlushGS .
.SH RETURN VALUES
A 0 value is returned on success. A -1 value indicates
an error.
.SH ERRORS
The
.BR fsync
fails if:
.RS
.IP \fBEBADF\fR
.I Fd
is not a valid descriptor.
.IP \fBEINVAL\fR
.I Fd
refers to a socket, not to a file.
.IP \fBEIO\fR
An I/O error occurred while reading from or writing to the file system.
.RE
.SH SEE ALSO
.BR sync (2),
.BR sync (8),
.BR update (8),
the
.IR "GS/OS Reference Manual" .
.SH HISTORY
The
.BR fsync
function call appeared in 4.2BSD.

73
usr.man/man2/getdtablesize.2 Normal file
View File

@ -0,0 +1,73 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getdtablesize.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETDTABLESIZE 2 "22 February 1996" GNO "System Calls"
.SH NAME
.BR getdtablesize
\- get descriptor table size
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
.BR getdtablesize (void);
.SH DESCRIPTION
Each process has a fixed size descriptor table,
which is guaranteed to have at least 20 slots. The entries in
the descriptor table are numbered with small integers starting at 0.
The call
.BR getdtablesize
returns the size of this table.
.LP
This call is mainly intended for use on systems which have configurable
kernels. Since the GNO kernel is not yet configurable, this function
always returns
.BR OPEN_MAX .
.SH BUGS
The concept of the maximum number of concurrently open files is not
yet consistent between GS/OS, the GNO kernel, and the C library. For
example, the kernel uses
.BR OPEN_MAX
as the largest number of open files, yet GS/OS does not have a hard upper
limit. It is recommended for now that the return value of
.BR getdtablesize
be assumed in applications to be the largest number of open files, as
it is the smallest value.
.SH SEE ALSO
.BR close (2),
.BR dup (2),
.BR open (2),
.BR select (2)
.SH HISTORY
The
.BR getdtablesize
function call appeared in 4.2BSD.

81
usr.man/man2/getgid.2 Normal file
View File

@ -0,0 +1,81 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getgid.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETGID 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getgid ,
.BR getegid
\- get group process identification
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <unistd.h>
.sp 1
gid_t
.BR getgid (void);
.br
gid_t
.BR getegid (void);
.SH DESCRIPTION
The
.BR getgid
function returns the real group ID of the calling process,
.BR getegid
returns the effective group ID of the calling process.
.LP
The real group ID is specified at login time.
.LP
The real group ID is the group of the user who invoked the program.
As the effective group ID gives the process additional permissions
during the execution of
.I set-group-ID
mode processes,
.BR getgid
is used to determine the real-user-id of the calling process.
.SH ERRORS
The
.BR getgid
and
.BR getegid
functions are always successful, and no return value is reserved to
indicate an error.
.SH SEE ALSO
.BR getuid (2),
.BR setregid (2),
.BR setgid (2)
.SH STANDARDS
.BR Getgid
and
.BR getegid
conform to IEEE Std 1003.1-1988 (POSIX).

89
usr.man/man2/getpeername.2 Normal file
View File

@ -0,0 +1,89 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getpeername.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETPEERNAME 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getpeername
\- get name of connected peer
.SH SYNOPSIS
#include <sys/socket.h>
.sp 1
int
\fBgetpeername\fR (int \fIs\fR, struct sockaddr *\fIname\fR,
int *\fInamelen\fR);
.SH DESCRIPTION
.BR Getpeername
returns the name of the peer connected to
socket
.IR s .
The
.I namelen
parameter should be initialized to indicate
the amount of space pointed to by
.IR name .
On return it contains the actual size of the name
returned (in bytes).
The name is truncated if the buffer provided is too small.
.SH DIAGNOSTICS
A 0 is returned if the call succeeds, -1 if it fails.
.SH ERRORS
The call succeeds unless:
.RS
.IP \fBEBADF\fR
The argument
.I s
is not a valid descriptor.
.IP \fBENOTSOCK\fR
The argument
.I s
is a file, not a socket.
.IP \fBENOTCONN\fR
The socket is not connected.
.IP \fBENOBUFS\fR
Insufficient resources were available in the system
to perform the operation.
.IP \fBEFAULT\fR
The
.I name
parameter points to memory not in a valid part of the
process address space.
.RE
.SH SEE ALSO
.BR accept (2),
.BR bind (2),
.BR socket (2),
.BR getsockname (2)
.SH HISTORY
The
.BR getpeername
function call appeared in 4.2BSD.

112
usr.man/man2/getpgrp.2 Normal file
View File

@ -0,0 +1,112 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getpgrp.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETPGRP 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getpgrp
\- get process group
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
pid_t
\fB_getpgrp\fR (pid_t \fIpid\fR);
.br
pid_t
\fBgetpgrp\fR (void);
.SH DESCRIPTION
.BR getpgrp
returns the process group of the current process.
.BR _getpgrp
returns the process group of the process specified by
.IR pid .
.LP
Process groups are used for distribution of signals, and
by terminals to arbitrate requests for their input: processes
that have the same process group as the terminal are foreground
and may read, while others will block with a signal if they attempt
to read.
.LP
This call is thus used by programs such as
.BR csh (1)
to create
process groups
in implementing job control.
The
.BR tcgetpgrp
and
.BR tcsetpgrp
calls
are used to get/set the process group of the control terminal.
.SH RETURNS
On success, the requested process group is returned. On failure, -1 is
returned and
.BR errno
is set.
.SH STANDARDS
The
.BR getpgrp
function conforms to IEEE Std 1003.1-1988 (POSIX).
.SH COMPATIBILITY
This version of
.BR getpgrp
differs from past GNO (pre-v2.0.6) and Berkeley versions by not taking a
.I "pid_t pid"
argument.
This incompatibility is required by
POSIX 1003.1-88.
.IP "From the POSIX 1003.1-88 Rationale:"
4.3BSD provides a
.BR getpgrp
function that returns the process group ID for a specified process.
Although this function is used to support job control, all known
job-control shells always specify the calling process with this
function.
Thus, the simpler System V
.BR getpgrp
suffices, and the added complexity of the 4.3BSD
.BR getpgrp
has been omitted from POSIX.1.
.LP
The older version of
.BR getpgrp
which takes an argument is available as the non-standard function
.BR _getpgrp .
.SH SEE ALSO
.BR job_control (2),
.BR setpgid (2),
.BR termios (4)
.SH HISTORY
The
.BR getpgrp
function call appeared in 4.0BSD.

82
usr.man/man2/getpid.2 Normal file
View File

@ -0,0 +1,82 @@
.\" 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.
.\"
.\" @(#)getpid.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETPID 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getpid ,
.BR getppid
\- get parent or calling process identification
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
pid_t
.BR getpid (void);
.br
pid_t
.BR getppid (void);
.SH DESCRIPTION
.BR Getpid
returns
the process ID of
the calling process.
The ID is guaranteed to be unique and is
useful for constructing temporary file names.
.LP
Pids can range from zero (Kernel Null Process) to 32767. Some programs use
.BR getpid
to seed random number generators. A much better approach on the IIgs is
to use the horizontal and vertical positions fo the electron gun, which
can be obtained by reading the word value at absolute address 0xE0C02E.
.LP
.BR Getppid
returns the process ID of the parent
of the calling process.
.SH ERRORS
The
.BR getpid
and
.BR getppid
functions are always successful; no return value is reserved to
indicate an error.
.SH SEE ALSO
.BR fork (2),
.BR tctpgrp (2),
.BR ioctl (2),
.BR gethostid (3),
.IR "GNO Kernel Reference Manual" .
.SH STANDARDS
.BR Getpid
and
.BR getppid
conform to IEEE Std 1003.1-1988 (POSIX).

87
usr.man/man2/getsockname.2 Normal file
View File

@ -0,0 +1,87 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getsockname.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETSOCKNAME 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getsockname
\- get socket name
.SH SYNOPSIS
#include <sys/socket.h>
.sp 1
int
\fBgetsockname\fR (int \fIs\fR, struct sockaddr *\fIname\fR,
int *\fInamelen\fR);
.SH DESCRIPTION
.BR Getsockname
returns the current
.I name
for the specified socket. The
.I namelen
parameter should be initialized to indicate
the amount of space pointed to by
.IR name .
On return it contains the actual size of the name
returned (in bytes).
.SH DIAGNOSTICS
Zero is returned if the call succeeds, -1 if it fails.
.SH ERRORS
The call succeeds unless:
.RS
.IP \fBEBADF\fR
The argument
.I s
is not a valid descriptor.
.IP \fBENOTSOCK\fR
The argument
.I s
is a file, not a socket.
.IP \fBENOBUFS\fR
Insufficient resources were available in the system
to perform the operation.
.IP \fBEFAULT\fR
The
.I name
parameter points to memory not in a valid part of the
process address space.
.RE
.SH SEE ALSO
.BR bind (2),
.BR socket (2)
.SH BUGS
Names bound to sockets in the UNIX domain are inaccessible;
.BR getsockname
returns a zero length name.
.SH HISTORY
The
.BR getsockname
function call appeared in 4.2BSD.

344
usr.man/man2/getsockopt.2 Normal file
View File

@ -0,0 +1,344 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94
.\"
.TH GETSOCKOPT 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getsockopt ,
.BR setsockopt
\- get and set options on sockets
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBgetsockopt\fR (int \fIs\fR, int \fIlevel\fR, int \fIoptname\fR,
void *\fIoptval\fR, int *\fIoptlen\fR);
.sp 1
int
\fBsetsockopt\fR (int \fIs\fR, int \fIlevel\fR, int \fIoptname\fR,
const void *\fIoptval\fR, int \fIoptlen\fR);
.SH DESCRIPTION
.BR Getsockopt
and
.BR setsockopt
manipulate the
.IR options
associated with a socket. Options may exist at multiple
protocol levels; they are always present at the uppermost
socket level.
.LP
When manipulating socket options the level at which the
option resides and the name of the option must be specified.
To manipulate options at the socket level,
.I level
is specified as
.BR SOL_SOCKET .
To manipulate options at any
other level the protocol number of the appropriate protocol
controlling the option is supplied. For example,
to indicate that an option is to be interpreted by the TCP
protocol,
.I level
should be set to the protocol number of TCP; see
.BR getprotoent (3).
.LP
The parameters
.I optval
and
.I optlen
are used to access option values for
.BR setsockopt .
For
.BR getsockopt
they identify a buffer in which the value for the
requested option(s) are to be returned. For
.BR getsockopt ,
.I optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
.IR optval ,
and modified on return to indicate the actual size of
the value returned. If no option value is
to be supplied or returned,
.I optval
may be NULL.
.LP
.I Optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
The include file
<sys/socket.h>
contains definitions for
socket level options, described below.
Options at other protocol levels vary in format and
name; consult the appropriate entries in
section 4 of the manual.
.LP
Most socket-level options utilize an
.I int
parameter for
.IR optval .
For
.BR setsockopt ,
the parameter should be non-zero to enable a boolean option,
or zero if the option is to be disabled.
.BR SO_LINGER
uses a
.B "struct linger"
parameter, defined in <sys/socket.h>,
which specifies the desired state of the option and the
linger interval (see below).
.BR SO_SNDTIMEO
and
.BR SO_RCVTIMEO
use a
.B "struct timeval"
parameter, defined in <sys/time.h>.
.LP
The following options are recognized at the socket level.
Except as noted, each may be examined with
.BR getsockopt
and set with
.BR setsockopt .
.RS
.nf
SO_DEBUG enables recording of debugging information
SO_REUSEADDR enables local address reuse
SO_REUSEPORT enables duplicate address and port bindings
SO_KEEPALIVE enables keep connections alive
SO_DONTROUTE enables routing bypass for outgoing messages
SO_LINGER linger on close if data present
SO_BROADCAST enables permission to transmit broadcast messages
SO_OOBINLINE enables reception of out-of-band data in band
SO_SNDBUF set buffer size for output
SO_RCVBUF set buffer size for input
SO_SNDLOWAT set minimum count for output
SO_RCVLOWAT set minimum count for input
SO_SNDTIMEO set timeout value for output
SO_RCVTIMEO set timeout value for input
SO_TYPE get the type of the socket (get only)
SO_ERROR get and clear error on the socket (get only)
.fi
.RE
.LP
.BR SO_DEBUG
enables debugging in the underlying protocol modules.
.BR SO_REUSEADDR
indicates that the rules used in validating addresses supplied
in a
.BR bind (2)
call should allow reuse of local addresses.
.BR SO_REUSEPORT
allows completely duplicate bindings by multiple processes
if they all set
.BR SO_REUSEPORT
before binding the port.
This option permits multiple instances of a program to each
receive UDP/IP multicast or broadcast datagrams destined for the bound port.
.BR SO_KEEPALIVE
enables the
periodic transmission of messages on a connected socket. Should the
connected party fail to respond to these messages, the connection is
considered broken and processes using the socket are notified via a
.BR SIGPIPE
signal when attempting to send data.
.BR SO_DONTROUTE
indicates that outgoing messages should
bypass the standard routing facilities. Instead, messages are directed
to the appropriate network interface according to the network portion
of the destination address.
.LP
.BR SO_LINGER
controls the action taken when unsent messages
are queued on socket and a
.BR close (2)
is performed.
If the socket promises reliable delivery of data and
.BR SO_LINGER is set,
the system will block the process on the
.BR close (2)
attempt until it is able to transmit the data or until it decides it
is unable to deliver the information (a timeout period, termed the
linger interval, is specified in the
.BR setsockopt
call when
.BR SO_LINGER
is requested).
If
.BR SO_LINGER
is disabled and a
.BR close (2)
is issued, the system will process the close in a manner that allows
the process to continue as quickly as possible.
.LP
The option
.BR SO_BROADCAST
requests permission to send broadcast datagrams
on the socket.
Broadcast was a privileged operation in earlier versions of the system.
With protocols that support out-of-band data, the
.BR SO_OOBINLINE
option
requests that out-of-band data be placed in the normal data input queue
as received; it will then be accessible with
.BR recv (2)
or
.BR read (2)
calls without the
.BR MSG_OOB
flag.
Some protocols always behave as if this option is set.
.BR SO_SNDBUF
and
.BR SO_RCVBUF
are options to adjust the normal
buffer sizes allocated for output and input buffers, respectively.
The buffer size may be increased for high-volume connections,
or may be decreased to limit the possible backlog of incoming data.
The system places an absolute limit on these values.
.LP
.BR SO_SNDLOWAT
is an option to set the minimum count for output operations.
Most output operations process all of the data supplied
by the call, delivering data to the protocol for transmission
and blocking as necessary for flow control.
Nonblocking output operations will process as much data as permitted
subject to flow control without blocking, but will process no data
if flow control does not allow the smaller of the low water mark value
or the entire request to be processed.
A
.BR select (2)
operation testing the ability to write to a socket will return true
only if the low water mark amount could be processed.
The default value for
.BR SO_SNDLOWAT
is set to a convenient size for network efficiency, often 1024.
.BR SO_RCVLOWAT
is an option to set the minimum count for input operations.
In general, receive calls will block until any (non-zero) amount of data
is received, then return with the smaller of the amount available or the amount
requested.
The default value for
.BR SO_RCVLOWAT
is 1.
If
.BR SO_RCVLOWAT
is set to a larger value, blocking receive calls normally
wait until they have received the smaller of the low water mark value
or the requested amount.
Receive calls may still return less than the low water mark if an error
occurs, a signal is caught, or the type of data next in the receive queue
is different than that returned.
.LP
.BR SO_SNDTIMEO
is an option to set a timeout value for output operations.
It accepts a
.B "struct timeval"
parameter with the number of seconds and microseconds
used to limit waits for output operations to complete.
If a send operation has blocked for this much time,
it returns with a partial count
or with the error
EWOULDBLOCK
if no data were sent.
In the current implementation, this timer is restarted each time additional
data are delivered to the protocol,
implying that the limit applies to output portions ranging in size
from the low water mark to the high water mark for output.
.BR SO_RCVTIMEO
is an option to set a timeout value for input operations.
It accepts a
.B "struct timeval"
parameter with the number of seconds and microseconds
used to limit waits for input operations to complete.
In the current implementation, this timer is restarted each time additional
data are received by the protocol,
and thus the limit is in effect an inactivity timer.
If a receive operation has been blocked for this much time without
receiving additional data, it returns with a short count
or with the error
EWOULDBLOCK
if no data were received.
.LP
Finally,
.BR SO_TYPE
and
.BR SO_ERROR
are options used only with
.BR getsockopt .
.BR SO_TYPE
returns the type of the socket, such as
.BR SOCK_STREAM ;
it is useful for servers that inherit sockets on startup.
.BR SO_ERROR
returns any pending error on the socket and clears
the error status.
It may be used to check for asynchronous errors on connected
datagram sockets or for other asynchronous errors.
.SH RETURN VALUES
A 0 is returned if the call succeeds, -1 if it fails.
.SH ERRORS
The call succeeds unless:
.RS
.IP \fBEBADF\fR
The argument
.I s
is not a valid descriptor.
.IP \fBENOTSOCK\fR
The argument
.I s
is a file, not a socket.
.IP \fBENOPROTOOPT\fR
The option is unknown at the level indicated.
.IP \fBEFAULT\fR
The address pointed to by
.I optval
is not in a valid part of the process address space.
For
.BR getsockopt ,
this error may also be returned if
.I optlen
is not in a valid part of the process address space.
.RE
.SH SEE ALSO
.BR ioctl (2),
.BR socket (2),
.BR getprotoent (3)
.BR protocols (5)
.SH BUGS
Several of the socket options should be handled at lower levels of the system.
.SH HISTORY
The
.BR setsockopt
system call appeared in 4.2BSD.

113
usr.man/man2/gettimeofday.2 Normal file
View File

@ -0,0 +1,113 @@
.\" 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.
.\"
.\" @(#)gettimeofday.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETTIMEOFDAY 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR gettimeofday ,
.BR settimeofday
\- get/set date and time
.SH SYNOPSIS
#include <sys/time.h>
.sp 1
int
\fBgettimeofday\fR (struct timeval *\fItp\fR, struct timezone *\fItzp\fR);
.sp 1
int
\fBsettimeofday\fR (struct timeval *\fItp\fR, struct timezone *\fItzp\fR);
.SH DESCRIPTION
The system's notion of the current Greenwich time and the current time
zone is obtained with the
.BR gettimeofday
call, and set with the
.BR settimeofday
call. The time is expressed in seconds and microseconds
since midnight (0 hour), January 1, 1970. The resolution of the system
clock is hardware dependent, and the time may be updated continuously or
in ``ticks.'' If
.I tp
or
.I tzp
is NULL, the associated time
information will not be returned or set.
.LP
The structures pointed to by
.I tp
and
.I tzp
are defined in <sys/time.h> as:
.nf
struct timeval {
long tv_sec; /* seconds since Jan. 1, 1970 */
long tv_usec; /* and microseconds */
};
struct timezone {
int tz_minuteswest; /* of Greenwich */
int tz_dsttime; /* type of dst correction to apply */
};
.fi
.LP
The
.I timezone
structure indicates the local time zone
(measured in minutes of time westward from Greenwich),
and a flag that, if nonzero, indicates that
Daylight Saving time applies locally during
the appropriate part of the year.
.LP
Only the super-user may set the time of day or time zone.
.SH RETURN
A 0 return value indicates that the call succeeded.
A -1 return value indicates an error occurred, and in this
case an error code is stored into the global variable
.IR errno .
.SH BUGS
For GNO,
.BR settimeofday
is not currently implemented.
.BR gettimeofday
is a minimal implementation that stores into \fItp\fR->sec the
value returned by
.BR time (2).
The \fItp\fR->usec field is set to zero.
.SH SEE ALSO
.BR date (1),
.BR adjtime (2),
.BR ctime (3),
.BR clocks (7),
.BR timed (8)
.SH HISTORY
The
.BR settimeofday
function call appeared in 4.2BSD.

80
usr.man/man2/getuid.2 Normal file
View File

@ -0,0 +1,80 @@
.\" 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.
.\"
.\" @(#)getuid.2 8.1 (Berkeley) 6/4/93
.\"
.TH GETUID 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR getuid ,
.BR geteuid
\- get user identification
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <unistd.h>
.sp 1
uid_t
.BR getuid (void);
.br
uid_t
.BR geteuid (void);
.SH DESCRIPTION
The
.BR getuid
function returns the real user ID of the calling process.
The
.BR geteuid
function
returns the effective user ID of the calling process.
.LP
The real user ID is that of the user who has invoked the program.
As the effective user ID
gives the process additional permissions during
execution of
.I set-user-ID
mode processes,
.BR getuid
is used to determine the real-user-id of the calling process.
.SH ERRORS
The
.BR getuid
and
.BR geteuid
functions are always successful, and no return value is reserved to
indicate an error.
.SH SEE ALSO
.BR getgid (2),
.BR setreuid (2)
.SH STANDARDS
.BR Geteuid
and
.BR getuid
conform to IEEE Std 1003.1-1988 (POSIX).

694
usr.man/man2/intro.2 Normal file
View File

@ -0,0 +1,694 @@
.\" Copyright (c) 1993, 1980198319861991
.\" 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.
.\"
.\" @(#)intro.2 8.3 (Berkeley) 12/11/93
.\"
.TH INTRO 2 "29 January 1997" GNO "System Calls"
.SH NAME
.BR intro
\- introduction to system calls and error numbers
.SH SYNOPSIS
#include <sys/errno.h>
.SH DESCRIPTION
This section provides an overview of the GNO system calls,
their error returns, and other common definitions and concepts.
Some functions listed in this chapter are not actually implemented as
kernel traps, but have been listed as such because they would be
system calls on a traditional Unix system.
.LP
The
.BR SYNOPSIS
section of each manual page gives the prototype for the function(s)
described, along with a listing of the header files which provide
the prototypes. The sequence of header file inclusion may be important,
so they should be included in the sequence given.
.LP
The
.BR DESCRIPTION
section gives the detailed description of the system call.
.LP
Reference may be made to symbolic links or other features
or functions that are either unimplemented or otherwise unavailable
under GNO. This information has often been obtained from the original
BSD manual pages. In most cases such information has been retained
in the GNO manual pages either because such functionality is planned
or because the information is relevent to code intended to run on
other BSD operating systems.
.SH DIAGNOSTICS
Nearly all of the system calls provide an error number in the external
variable
.BR errno ,
which is defined as:
.RS
.LP
extern int \fBerrno\fR;
.LP
.RE
When a system call detects an error,
it returns an integer value
indicating failure (usually -1)
and sets the variable
.BR errno
accordingly. (This allows interpretation of the failure on receiving
a -1 and to take action accordingly.)
Successful calls never set
.BR errno ;
once set, it remains until another error occurs.
It should only be examined after an error.
Note that a number of system calls overload the meanings of these
error numbers, and that the meanings must be interpreted according
to the type and circumstances of the call.
.LP
The following is a complete list of the errors used in GNO and their
names as given in <sys/errno.h>. The first twelve (up to
.BR ENOSPC )
are also used by the ORCA/Shell.
.RS
.IP "\fBENOERR\fR -- Error 0"
Not used.
.IP "\fBEDOM\fR -- Numerical argument out of domain"
A numerical input argument was outside the defined domain of the mathematical
function.
.IP "\fBERANGE\fR -- Numerical result out of range"
A numerical result of the function was too large to fit in the
available space (perhaps exceeded precision).
.IP "\fBENOMEM\fR -- Cannot allocate memory"
The new process image required more memory than was allowed by the hardware
or by system-imposed memory management constraints.
.IP "\fBENOENT\fR -- No such file or directory"
A component of a specified pathname did not exist, or the
pathname was an empty string.
.IP "\fBEIO\fR -- Input/output error"
Some physical input or output error occurred.
.sp 1
Any GS/OS errors that occur and which do not have any other suitable
.BR errno
counterparts will be mapped to this error.
.IP "\fBEINVAL\fR -- Invalid argument"
Some invalid argument was supplied. (For example,
specifying an undefined signal to a
.BR signal
or
.BR kill
function).
.IP "\fBEBADF\fR -- Bad file descriptor"
A file descriptor argument was out of range, referred to no open file,
or a read (write) request was made to a file that was only open for
writing (reading).
.IP "\fBEMFILE\fR -- Too many open files"
(The limit on the number of
open files per process is 32. This is configurable under some versions
of Unix, but not under GNO.)
.BR Getdtablesize (2)
will obtain the current limit.
.IP "\fBEACCES\fR -- Permission denied"
An attempt was made to access a file in a way forbidden
by its file access permissions.
.sp 1
The default Orca/C header files use
.BR EACCESS
(with two
.BR S \'s)
for this macro, but GNO does not since it causes a conflict with
standard macros in the <arpa/tftp.h> header.
.IP "\fBEEXIST\fR -- File exists"
An existing file was mentioned in an inappropriate context.
.IP "\fBENOSPC\fR -- Device out of space"
A
.BR write
to an ordinary file, the creation of a
directory or symbolic link, or the creation of a directory
entry failed because no more disk blocks were available
on the file system, or (for filesystems using inodes)
the allocation of an inode for a newly
created file failed because no more inodes were available
on the file system.
.IP "\fBEPERM\fR -- Operation not permitted"
An attempt was made to perform an operation limited to processes
with appropriate privileges or to the owner of a file or other
resources.
.IP "\fBESRCH\fR -- No such process"
No process could be found corresponding to that specified by the given
process ID.
.IP "\fBEINTR\fR -- Interrupted function call"
An asynchronous signal (such as
.BR SIGINT
or
.BR SIGQUIT )
was caught by the process during the execution of an interruptible
function. If the signal handler performs a normal return, the
interrupted function call will seem to have returned the error condition.
.IP "\fBE2BIG\fR -- Arg list too long"
The number of bytes used for the argument and environment
list of the new process exceeded the current limit
of 4096 bytes (NCARGS in <sys/param.h>).
.IP "\fBENOEXEC\fR -- Exec format error"
A request was made to execute a file
that, although it has the appropriate permissions,
was not in the format required for an
executable file.
.IP "\fBECHILD\fR -- \&No child processes"
A
.BR wait
or
.BR waitpid
function was executed by a process that had no existing or unwaited-for
child processes.
.IP "\fBEAGAIN\fR -- Resource temporarily unavailable"
This is a temporary condition and later calls to the
same routine may complete normally.
.IP "\fBENOTDIR\fR -- Not a directory"
A component of the specified pathname existed, but it was
not a directory, when a directory was expected.
.IP "\fBENOTTY\fR -- Inappropriate ioctl for device"
A control function (see
.BR ioctl (2))
was attempted for a file or
special device for which the operation was inappropriate.
.IP "\fBEPIPE\fR -- Broken pipe"
A write on a pipe, socket or
.BR FIFO
for which there is no process
to read the data.
.IP "\fBESPIPE\fR -- Illegal seek"
An
.BR lseek
function was issued on a socket, pipe or
.BR FIFO .
.IP "\fBENOTBLK\fR -- Not a block device"
A block device operation was attempted on a non-block device or file.
.IP "\fBEISDIR\fR -- Is a directory"
An attempt was made to open a directory with write mode specified.
.IP "\fBENOTSOCK\fR -- Socket operation on non-socket"
Self-explanatory.
.IP "\fBEDESTADDRREQ\fR -- Destination address required"
A required address was omitted from an operation on a socket.
.IP "\fBEMSGSIZE\fR -- Message too long"
A message sent on a socket was larger than the internal message buffer
or some other network limit.
.IP "\fBEPROTOTYPE\fR -- Protocol wrong type for socket"
A protocol was specified that does not support the semantics of the
socket type requested. For example, you cannot use the
.BR ARPA
Internet
.BR UDP
protocol with type
.BR SOCK_STREAM .
.IP "\fBENOPROTOOPT\fR -- Protocol not available"
A bad option or level was specified in a
.BR getsockopt (2)
or
.BR setsockopt (2)
call.
.IP "\fBEPROTONOSUPPORT\fR -- Protocol not supported"
The protocol has not been configured into the
system or no implementation for it exists.
.IP "\fBESOCKTNOSUPPORT\fR -- Socket type not supported"
The support for the socket type has not been configured into the
system or no implementation for it exists.
.IP "\fBEOPNOTSUPP\fR -- Operation not supported"
The attempted operation is not supported for the type of object referenced.
Usually this occurs when a file descriptor refers to a file or socket
that cannot support this operation,
for example, trying to
.IR accept
a connection on a datagram socket.
.IP "\fBEPFNOSUPPORT\fR -- Protocol family not supported"
The protocol family has not been configured into the
system or no implementation for it exists.
.IP "\fBEAFNOSUPPORT\fR -- Address family not supported by protocol family"
An address incompatible with the requested protocol was used.
For example, you shouldn't necessarily expect to be able to use
.BR NS
addresses with
.BR ARPA
Internet protocols.
.IP "\fBEADDRINUSE\fR -- Address already in use"
Only one usage of each address is normally permitted.
.IP "\fBEADDRNOTAVAIL\fR -- Cannot assign requested address"
Normally results from an attempt to create a socket with an
address not on this machine.
.IP "\fBENETDOWN\fR -- Network is down"
A socket operation encountered a dead network.
.IP "\fBENETUNREACH\fR -- Network is unreachable"
A socket operation was attempted to an unreachable network.
.IP "\fBENETRESET\fR -- Network dropped connection on reset"
The host you were connected to crashed and rebooted.
.IP "\fBECONNABORTED\fR -- Software caused connection abort"
A connection abort was caused internal to your host machine.
.IP "\fBECONNRESET\fR -- Connection reset by peer"
A connection was forcibly closed by a peer. This normally
results from a loss of the connection on the remote socket
due to a timeout or a reboot.
.IP "\fBENOBUFS\fR -- \&No buffer space available"
An operation on a socket or pipe was not performed because
the system lacked sufficient buffer space or because a queue was full.
.IP "\fBEISCONN\fR -- Socket is already connected"
A
.BR connect
request was made on an already connected socket; or,
a
.BR sendto
or
.BR sendmsg
request on a connected socket specified a destination
when already connected.
.IP "\fBENOTCONN\fR -- Socket is not connected"
An request to send or receive data was disallowed because
the socket was not connected and (when sending on a datagram socket)
no address was supplied.
.IP "\fBESHUTDOWN\fR -- Cannot send after socket shutdown"
A request to send data was disallowed because the socket
had already been shut down with a previous
.BR shutdown (2)
call.
.IP "\fBETIMEDOUT\fR -- Operation timed out"
A
.BR connect
or
.BR send
request failed because the connected party did not
properly respond after a period of time. (The timeout
period is dependent on the communication protocol.)
.IP "\fBECONNREFUSED\fR -- Connection refused"
No connection could be made because the target machine actively
refused it. This usually results from trying to connect
to a service that is inactive on the foreign host.
.IP "\fBEWOULDBLOCK\fR -- Operation would block"
An operation was attempted on a non-blocking file descriptor that
would cause the calling process to block.
.IP "\fBEINPROGRESS\fR -- Operation now in progress"
An operation that takes a long time to complete (such as
a
.BR connect (2))
was attempted on a non-blocking object (see
.BR fcntl (2)).
.IP "\fBEALREADY\fR -- Operation already in progress"
An operation was attempted on a non-blocking object that already
had an operation in progress.
.IP "\fBEFAULT\fR -- Bad address"
The system detected an invalid address in attempting to
use an argument of a call.
.IP "\fBENODEV\fR -- Operation not supported by device"
An attempt was made to apply an inappropriate
function to a device,
for example,
trying to read a write-only device such as a printer.
.IP "\fBEHOSTDOWN\fR -- Host is down"
A socket operation failed because the destination host was down.
.IP "\fBEHOSTUNREACH\fR -- No route to host"
A socket operation was attempted to an unreachable host.
.RE
.LP
The following errors may be present in various BSD sources, but are
not currently used in GNO:
.LP
.RS
.IP "\fBENXIO\fR -- \&No such device or address"
Input or output on a special file referred to a device that did not
exist, or
made a request beyond the limits of the device.
This error may also occur when, for example,
a tape drive is not online or no disk pack is
loaded on a drive.
.IP "\fBEDEADLK\fR -- Resource deadlock avoided"
An attempt was made to lock a system resource that
would have resulted in a deadlock situation.
.IP "\fBEBUSY\fR -- Resource busy"
An attempt to use a system resource which was in use at the time
in a manner which would have conflicted with the request.
.IP "\fBEXDEV\fR -- Improper link"
A hard link to a file on another file system
was attempted.
.IP "\fBENFILE\fR -- Too many open files in system"
Maximum number of file descriptors allowable on the system
has been reached and a requests for an open cannot be satisfied
until at least one has been closed.
.IP "\fBETXTBSY\fR -- Text file busy"
The new process was a pure procedure (shared text) file
which was open for writing by another process, or
while the pure procedure file was being executed an
.BR open
call requested write access.
.IP "\fBEFBIG\fR -- File too large"
The size of a file exceeded the maximum (about
.if t 2\u\s-231\s+2\d
.if n 2.1E9
bytes).
.IP "\fBEROFS\fR -- Read-only file system"
An attempt was made to modify a file or directory
was made
on a file system that was read-only at the time.
.IP "\fBEMLINK\fR -- Too many links"
Maximum allowable hard links to a single file has been exceeded (limit
of 32767 hard links per file).
.IP "\fBELOOP\fR -- Too many levels of symbolic links"
A path name lookup involved more than 8 symbolic links.
.IP "\fBENAMETOOLONG\fR -- File name too long"
A component of a path name exceeded 255 (MAXNAMELEN)
characters, or an entire path name exceeded 1023 (MAXPATHLEN-1) characters.
.IP "\fBENOTEMPTY\fR -- Directory not empty"
A directory with entries other than
.BR \&.
and
.BR \&..
was supplied to a remove directory or rename call.
.IP "\fBEPROCLIM\fR -- Too many processes"
.IP "\fBEUSERS\fR -- Too many users"
The quota system ran out of table entries.
.IP "\fBEDQUOT\fR -- Disc quota exceeded"
A
.BR write
to an ordinary file, the creation of a
directory or symbolic link, or the creation of a directory
entry failed because the user's quota of disk blocks was
exhausted, or the allocation of an inode for a newly
created file failed because the user's quota of inodes
was exhausted.
.IP "\fBESTALE\fR -- Stale NFS file handle"
An attempt was made to access an open file (on an
.BR NFS
filesystem)
which is now unavailable as referenced by the file descriptor.
This may indicate the file was deleted on the
.BR NFS
server or some
other catastrophic event occurred.
.IP "\fBEBADRPC\fR -- RPC struct is bad"
Exchange of
.BR RPC
information was unsuccessful.
.IP "\fBERPCMISMATCH\fR -- RPC version wrong"
The version of
.BR RPC
on the remote peer is not compatible with
the local version.
.IP "\fBEPROGUNAVAIL\fR -- RPC prog. not avail"
The requested program is not registered on the remote host.
.IP "\fBEPROGMISMATCH\fR -- Program version wrong"
The requested version of the program is not available
on the remote host
.BR RPC .
.IP "\fBEPROCUNAVAIL\fR -- Bad procedure for program"
An
.BR RPC
call was attempted for a procedure which doesn't exist
in the remote program.
.IP "\fBENOLCK\fR -- No locks available"
A system-imposed limit on the number of simultaneous file
locks was reached.
.IP "\fBENOSYS\fR -- Function not implemented"
Attempted a system call that is not available on this
system.
.RE
.SH DEFINITIONS
.IP "\fBProcess ID\fR"
Each active process in the system is uniquely identified by a non-negative
integer called a process ID. The range of this ID is from 0 to 30000.
.IP "\fBParent process ID\fR"
A new process is created by a currently active process; (see
.BR fork (2)).
The parent process ID of a process is initially the process ID of its creator.
If the creating process exits,
the parent process ID of each child is set to the ID of a system process,
.BR init .
.IP "\fBProcess Group\fR"
Each active process is a member of a process group that is identified by
a non-negative integer called the process group ID. This is the process
ID of the group leader. This grouping permits the signaling of related
processes (see
.BR termios (4))
and the job control mechanisms of
.BR csh (1).
.IP \fBSession\fR
A session is a set of one or more process groups.
A session is created by a successful call to
.BR setsid (2),
which causes the caller to become the only member of the only process
group in the new session.
.IP "\fBSession leader\fR"
A process that has created a new session by a successful call to
.BR setsid (2),
is known as a session leader.
Only a session leader may acquire a terminal as its controlling terminal (see
.BR termios (4)).
.IP "\fBControlling process\fR"
A session leader with a controlling terminal is a controlling process.
.IP "\fBControlling terminal\fR"
A terminal that is associated with a session is known as the controlling
terminal for that session and its members.
.IP "\fBTerminal Process Group ID\fR"
A terminal may be acquired by a session leader as its controlling terminal.
Once a terminal is associated with a session, any of the process groups
within the session may be placed into the foreground by setting
the terminal process group ID to the ID of the process group.
This facility is used
to arbitrate between multiple jobs contending for the same terminal;
(see
.BR csh (1)
and
.BR tty (4)).
.IP "\fBOrphaned Process Group\fR"
A process group is considered to be
.IR orphaned
if it is not under the control of a job control shell.
More precisely, a process group is orphaned
when none of its members has a parent process that is in the same session
as the group,
but is in a different process group.
Note that when a process exits, the parent process for its children
is changed to be
.BR init ,
which is in a separate session.
Not all members of an orphaned process group are necessarily orphaned
processes (those whose creating process has exited).
The process group of a session leader is orphaned by definition.
.IP "\fBReal User ID\fR and \fBReal Group ID\fR"
Each user on the system is identified by a positive integer
termed the real user ID.
.sp 1
Each user is also a member of one or more groups.
One of these groups is distinguished from others and
used in implementing accounting facilities. The positive
integer corresponding to this distinguished group is termed
the real group ID.
.sp 1
All processes have a real user ID and real group ID.
These are initialized from the equivalent attributes
of the process that created it.
.IP "\fBEffective User Id, Effective Group Id\fR, and \fBGroup Access List\fR"
Access to system resources is governed by two values:
the effective user ID, and the group access list.
The first member of the group access list is also known as the
effective group ID.
(In POSIX.1, the group access list is known as the set of supplementary
group IDs, and it is unspecified whether the effective group ID is
a member of the list.)
.sp 1
The effective user ID and effective group ID are initially the
process's real user ID and real group ID respectively. Either
may be modified through execution of a set-user-ID or set-group-ID
file (possibly by one its ancestors) (see
.BR execve (2)).
By convention, the effective group ID (the first member of the group access
list) is duplicated, so that the execution of a set-group-ID program
does not result in the loss of the original (real) group ID.
.sp 1
The group access list is a set of group IDs
used only in determining resource accessibility. Access checks
are performed as described below in ``File Access Permissions''.
.IP "\fBSaved Set User ID\fR and \fBSaved Set Group ID\fR"
When a process executes a new file, the effective user ID is set
to the owner of the file if the file is set-user-ID, and the effective
group ID (first element of the group access list) is set to the group
of the file if the file is set-group-ID.
The effective user ID of the process is then recorded as the saved set-user-ID,
and the effective group ID of the process is recorded as the saved set-group-ID.
These values may be used to regain those values as the effective user
or group ID after reverting to the real ID (see
.BR setuid (2)).
(In POSIX.1, the saved set-user-ID and saved set-group-ID are optional,
and are used in setuid and setgid, but this does not work as desired
for the super-user.)
.IP \fBSuper-user\fR
A process is recognized as a
.IR super-user
process and is granted special privileges if its effective user ID is 0.
.IP "\fBSpecial Processes\fR"
The processes with process IDs of 0, 1, and 2 are special.
Process 0 is the scheduler. Process 1 is the initialization process
.BR init ,
and is the ancestor of every other process in the system.
It is used to control the process structure.
Process 2 is the paging daemon.
.IP \fBDescriptor\fR
An integer assigned by the system when a file is referenced
by
.BR open (2)
or
.BR dup (2),
or when a socket is created by
.BR pipe (2),
.BR socket (2)
or
.BR socketpair (2),
which uniquely identifies an access path to that file or socket from
a given process or any of its children.
.IP "\fBFile Name\fR"
names consisting of up to 255 (MAXNAMELEN)
characters may be used to name
an ordinary file, special file, or directory.
.sp 1
These characters may be selected from the set of all
.BR ASCII
character
excluding 0 (NUL) and the
.BR ASCII
code for
.BR \&/
(slash). (The parity bit,
bit 7, must be 0.)
.sp 1
Note that it is generally unwise to use
.BR \&* ,
.BR \&? ,
.BR \&[
or
.BR \&]
as part of
file names because of the special meaning attached to these characters
by the shell.
.IP "\fBPath Name\fR"
A path name is a
.BR NULL \-terminated
character string starting with an
optional slash
.BR \&/ ,
followed by zero or more directory names separated
by slashes, optionally followed by a file name.
The total length of a path name must be less than 1024 (MAXPATHLEN)
characters.
.sp 1
If a path name begins with a slash, the path search begins at the
.IR root
directory.
Otherwise, the search begins from the current working directory.
A slash by itself names the root directory. An empty
pathname refers to the current directory.
.IP \fBDirectory\fR
A directory is a special type of file that contains entries
that are references to other files.
Directory entries are called links. By convention, a directory
contains at least two links,
.BR \&.
and
.BR \&.. ,
referred to as
.IR dot
and
.IR dot-dot
respectively. Dot refers to the directory itself and
dot-dot refers to its parent directory.
.IP "\fBRoot Directory\fR and \fBCurrent Working Directory\fR"
Each process has associated with it a concept of a root directory
and a current working directory for the purpose of resolving path
name searches. A process's root directory need not be the root
directory of the root file system.
.IP "\fBFile Access Permissions\fR"
Every file in the file system has a set of access permissions.
These permissions are used in determining whether a process
may perform a requested operation on the file (such as opening
a file for writing). Access permissions are established at the
time a file is created. They may be changed at some later time
through the
.BR chmod (2)
call.
.sp 1
File access is broken down according to whether a file may be: read,
written, or executed. Directory files use the execute
permission to control if the directory may be searched.
.sp 1
File access permissions are interpreted by the system as
they apply to three different classes of users: the owner
of the file, those users in the file's group, anyone else.
Every file has an independent set of access permissions for
each of these classes. When an access check is made, the system
decides if permission should be granted by checking the access
information applicable to the caller.
.sp 1
Read, write, and execute/search permissions on
a file are granted to a process if:
.sp 1
The process's effective user ID is that of the super-user. (Note:
even the super-user cannot execute a non-executable file.)
.sp 1
The process's effective user ID matches the user ID of the owner
of the file and the owner permissions allow the access.
.sp 1
The process's effective user ID does not match the user ID of the
owner of the file, and either the process's effective
group ID matches the group ID
of the file, or the group ID of the file is in
the process's group access list,
and the group permissions allow the access.
.sp 1
Neither the effective user ID nor effective group ID
and group access list of the process
match the corresponding user ID and group ID of the file,
but the permissions for ``other users'' allow access.
.sp 1
Otherwise, permission is denied.
.IP "\fBSockets\fR and \fBAddress Families\fR"
.sp 1
A socket is an endpoint for communication between processes.
Each socket has queues for sending and receiving data.
.sp 1
Sockets are typed according to their communications properties.
These properties include whether messages sent and received
at a socket require the name of the partner, whether communication
is reliable, the format used in naming message recipients, etc.
.sp 1
Each instance of the system supports some
collection of socket types; consult
.BR socket (2)
for more information about the types available and
their properties.
.sp 1
Each instance of the system supports some number of sets of
communications protocols. Each protocol set supports addresses
of a certain format. An Address Family is the set of addresses
for a specific group of protocols. Each socket has an address
chosen from the address family in which the socket was created.
.SH SEE ALSO
.BR intro(3) ,
.BR perror (3),
the
.IR "GNO Kernel Reference Manual" .

106
usr.man/man2/ioctl.2 Normal file
View File

@ -0,0 +1,106 @@
.\" 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.
.\"
.\" @(#)ioctl.2 8.2 (Berkeley) 12/11/93
.\"
.TH IOCTL 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR ioctl
\- control device
.SH SYNOPSIS
.br
#include <sys/ioctl.h>
.sp 1
int
\fBioctl\fR (int \fId\fR, unsigned long \fIrequest\fR, void *\fIargp\fR);
.SH DESCRIPTION
The
.BR ioctl
function manipulates the underlying device parameters of special files.
In particular, many operating
characteristics of character special files (e.g. terminals)
may be controlled with
.BR ioctl
requests.
The argument
.I d
must be an open file descriptor.
.LP
An ioctl
.I request
has encoded in it whether the argument is an 'in'
parameter or 'out'
parameter, and the size of the argument
.I argp
in bytes.
Macros and defines used in specifying an ioctl
.I request
are located in the file <sys/ioctl.h>.
.LP
The writeups of various devices in chapter 4 discuss how
.BR ioctl
applies to them.
.SH RETURN VALUES
If an error has occurred, a value of -1 is returned and
.IR errno
is set to indicate the error.
.SH ERRORS
.BR Ioctl
will fail if:
.RS
.IP \fBEBADF\fR
.I d
is not a valid descriptor.
.IP \fBENOTTY\fR
.I d
is not associated with a character
special device.
.IP \fBENOTTY\fR
The specified request does not apply to the kind
of object that the descriptor
.I d
references.
.IP \fBEINVAL\fR
.I Request
or
.I argp
is not valid.
.RE
.SH SEE ALSO
.BR mt (1),
.BR execve (2),
.BR fcntl (2),
.BR tty (4),
.BR intro (4)
.SH HISTORY
An
.BR ioctl
function call appeared in Version 7 AT&T UNIX.

144
usr.man/man2/jobcontrol.2 Normal file
View File

@ -0,0 +1,144 @@
.\"
.\" $Id: jobcontrol.2,v 1.1 1997/02/27 07:32:14 gdr Exp $
.\"
.TH "JOBCONTROL" 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR settpgrp ,
.BR tcnewpgrp ,
.BR tctpgrp
\- interface for the new job control model
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int
\fBtcnewpgrp\fR(int \fIfdtty\fR);
.br
int
\fBsettpgrp\fR(int \fIfdtty\fR);
.br
int
\fBtctpgrp\fR(int \fIfdtty\fR, int \fIpid\fR);
.SH 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 (such as ^C) typed on a
tty with a non-zero process group produce signals sent to every process
which is a member of the group.
.LP
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
it is configured to do so with
.BR ioctl (2).
When a tty file is first opened, it is assigned process group zero
.RB ( init (8)
has process group zero). As
.BR init
launches login processes on various ttys, it assigns process groups
to those ttys and processes.
.LP
.BR tcnewpgrp
allocates a new process group and assigns it to the terminal referred
to by
.IR fdtty .
If the calling process is not in the foreground, it is sent
.BR SIGTTOU .
.LP
.BR settpgrp
sets the current process to have the process group as
.IR fdtty .
.LP
.BR tctpgrp
sets the tty referred to by
.IR fdtty
to the same process group as the process
.IR pid ,
where
.IR pid
is the current process or a descendant of it.
.SH RETURN VALUE
These calls will return zero on success, otherwise they'll return -1
and set
.BR errno
accordingly.
.SH ERRORS
.IP \fBEBADF\fR
.IR fdtty
is not a valid file descriptor.
.IP \fBENOTTY\fR
.IR fdtty
does not refer to a terminal file.
.IP \fBESRCH\fR
.IR pid
is not a valid process identifier.
.SH EXAMPLES
The following are some example uses of the job control interface.
.RS
.LP
Forking a pipeline in a job-control shell: The shell starts with
.BR tcnewpgrp
so that the tty is in the new process group before there are even any
children. It then
.BR fork s
each process in the pipeline. Each process does
.BR settpgrp ,
thus joining the new process group.
.LP
Handling a stopped child process: When the shell sees that a pipeline
has stopped or exited, it does
.BR tctpgrp
to set the tty to its own process group. To resume the pipeline it does
.BR tctpgrp
where
.IR pid
is one of the child processes, then sends
.BR SIGCONT .
.LP
Starting a process under a new tty: When, for instance,
telnetd (8)
wants to grap a pseudo-tty, it opens the pty and
.BR fork s
a child process. The child does
.BR tcnewpgrp
to give the tty a real process group, then
.BR settpgrp
to place itself into the foregroup.
.RE
Security under this scheme is trivial. there is no way a process can join
a process group except by
.BR settpgrp ,
and that requires a descriptor open to a tty with that
.IR pgrp .
To make a tty have that
.Ir pgrp
requires either
.BR tcnewpgrp
(in which case nobody else is using the
.IR pgrp ),
or
.BR tctpgrp
(which reduces to the first problem of having a process in the process
group).
.LP
Note that 'using' must be defined as use both by ttys and by processes; the
kernel keeps a table of
.IR pgrp s,
each with a total tty and process reference count. When the reference
count reaches zero, the
.IR pgrp
is automatically deallocated.
.SH SEE ALSO
.BR ioctl (2),
.BR kill (2),
.BR signal (2),
.BR tty (4),
.IR "GNO Shell Reference Manual" .
.SH 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.
.LP
The GNO implementation was written strictly from specs.

48
usr.man/man2/kernStatus.2 Normal file
View File

@ -0,0 +1,48 @@
.\"
.\" $Id: kernStatus.2,v 1.1 1997/02/27 07:32:14 gdr Exp $
.\"
.TH KERNSTATUS 2 "29 January 1997" GNO "System Calls"
.SH NAME
.BR kernStatus ,
.BR kernVersion
\- detect presence and version of GNO kernel
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int
\fBkernStatus\fR (void);
.br
int
\fBkernVersion\fR (void);
.SH DESCRIPTION
.BR kernStatus
can be used to determine whether or not the GNO kernel is active.
You may use this function to abort programs that use GNO-specific features,
or to allow them to enable non-GNO environment-specific code.
.LP
If the GNO kernel is not active, the global variable
.BR _toolErr
will be non-zero on return from
.BR kernStatus .
This value is also accessible through the function
.BR toolerror (3).
C programmers may prefer to use
.BR needsgno (3)
for brevity.
.LP
.BR kernVersion
returns the kernel version in the same fashion as the standard IIgs
ToolBox calls. For example, a return value of
.B 0x0201
indicates a version of
.BR 2.1 .
.LP
Note that both of these functions are inline system calls; you
.IR must
include the <gno/gno.h> header or they will wind up as being
unresolved symbols when your program is linked.
.SH SEE ALSO
.BR needsgno (2),
.BR toolerror (3),
the
.IR "GNO Kernel Reference Manual" .

142
usr.man/man2/kill.2 Normal file
View File

@ -0,0 +1,142 @@
.\" 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.
.\"
.\" @(#)kill.2 8.3 (Berkeley) 4/19/94
.\"
.TH KILL 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR kill
\- send signal to a process
.SH SYNOPSIS
.br
#include <signal.h>
.sp 1
int
\fBkill\fR (pid_t \fIpid\fR, int \fIsig\fR);
.SH DESCRIPTION
The
.BR kill
function sends the signal given by
.I sig
to
.IR pid ,
a
process or a group of processes.
Signals are software interrupts; they act just like hardware interrupts
and can also be used for basic IPC (inter-process communication).
.LP
.I Sig
may be one of the signals specified in
.BR signal (2)
or it may be 0, in which case
error checking is performed but no
signal is actually sent.
This can be used to check the validity of
.IR pid .
.LP
For a process to have permission to send a signal to a process designated
by
.IR pid ,
the real or effective user ID of the receiving process must match
that of the sending process or the user must have appropriate privileges
(such as given by a set-user-ID program or the user is the super-user).
A single exception is the signal SIGCONT, which may always be sent
to any descendant of the current process.
.LP
If
.IR pid
is greater than zero,
.I sig
is sent to the process whose ID is equal to
.I pid.
.LP
If
.IR pid
is zero,
.I sig
is sent to all processes whose group ID is equal
to the process group ID of the sender, and for which the
process has permission;
this is a variant of
.BR killpg (2).
If
.IR pid
is -1, and
if the user has super-user privileges,
the signal is sent to all processes excluding
system processes and the process sending the signal.
If the user is not the super user, the signal is sent to all processes
with the same uid as the user excluding the process sending the signal.
No error is returned if any process could be signaled.
.LP
For compatibility with System V,
if the process number is negative but not -1,
the signal is sent to all processes whose process group ID
is equal to the absolute value of the process number.
This is a variant of
.BR killpg (2).
.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 ERRORS
.BR Kill
will fail and no signal will be sent if:
.RS
.IP \fBEINVAL\fR
.I Sig
is not a valid signal number.
.IP \fBESRCH\fR
No process can be found corresponding to that specified by
.RI ( pid )
.IP \fBESRCH\fR
The process id was given as 0
but the sending process does not have a process group.
.IP \fBEPERM\fR
The sending process is not the super-user and its effective
user id does not match the effective user-id of the receiving process.
When signaling a process group, this error is returned if any members
of the group could not be signaled.
.RE
.SH BUGS
Do not attempt to send signals from inside a CDA (Classic Desk Accessory)
or interrupt handler.
.SH SEE ALSO
.BR getpid (2),
.BR getpgrp (2),
.BR killpg (2),
.BR signal (2)
.SH STANDARDS
The
.BR kill
function is expected to
conform to IEEE Std 1003.1-1988 (POSIX).

101
usr.man/man2/listen.2 Normal file
View File

@ -0,0 +1,101 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)listen.2 8.2 (Berkeley) 12/11/93
.\"
.TH LISTEN 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR listen
\- listen for connections on a socket
.SH SYNOPSIS
.br
#include <sys/socket.h>
.sp 1
int
\fBlisten\fR (int \fIs\fR, int \fIbacklog\fR);
.SH DESCRIPTION
To accept connections, a socket
is first created with
.BR socket (2),
a willingness to accept incoming connections and
a queue limit for incoming connections are specified with
.BR listen ,
and then the connections are
accepted with
.BR accept (2).
The
.BR listen
call applies only to sockets of type
.BR SOCK_STREAM
or
.BR SOCK_SEQPACKET.
.LP
The
.I backlog
parameter defines the maximum length the queue of
pending connections may grow to.
If a connection
request arrives with the queue full the client may
receive an error with an indication of
ECONNREFUSED,
or, if the underlying protocol supports retransmission,
the request may be ignored so that retries may succeed.
.SH RETURN VALUES
A 0 return value indicates success; -1 indicates an error.
.SH ERRORS
.BR Listen
will fail if:
.RS
.IP \fBEBADF\fR
The argument
.I s
is not a valid descriptor.
.IP \fBENOTSOCK\fR
The argument
.I s
is not a socket.
.IP \fBEOPNOTSUPP\fR
The socket is not of a type that supports the operation
.BR listen .
.RE
.SH SEE ALSO
.BR accept (2),
.BR connect (2),
.BR socket (2)
.SH BUGS
The
.I backlog
is currently limited (silently) to 32.
.SH HISTORY
The
.BR listen
function call appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

139
usr.man/man2/lseek.2 Normal file
View File

@ -0,0 +1,139 @@
.\" 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.
.\"
.\" @(#)lseek.2 8.3 (Berkeley) 4/19/94
.\"
.TH LSEEK 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR lseek
\- reposition read/write file offset
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
off_t
\fBlseek\fR (int \fIfildes\fR, off_t \fIoffset\fR, int \fIwhence\fR);
.SH DESCRIPTION
The
.BR lseek
function repositions the offset of the file descriptor
.I fildes
to the
argument
.I offset
according to the directive
.I whence.
The argument
.I fildes
must be an open
file descriptor.
.BR Lseek
repositions the file pointer
.I fildes
as follows:
.RS
.It
If
.I whence
is
.BR SEEK_SET ,
the offset is set to
.I offset
bytes.
.It
If
.I whence
is
.BR SEEK_CUR ,
the offset is set to its current location plus
.I offset
bytes.
.It
If
.I whence
is
.BR SEEK_END ,
the offset is set to the size of the
file plus
.I offset
bytes.
.RE
.LP
The
.BR lseek
function allows the file offset to be set beyond the end
of the existing end-of-file of the file. If data is later written
at this point, subsequent reads of the data in the gap return
bytes of zeros (until data is actually written into the gap).
.LP
Some devices are incapable of seeking. The value of the pointer
associated with such a device is undefined.
.SH RETURN VALUES
Upon successful completion,
.BR lseek
returns the resulting offset location as measured in bytes from the
beginning of the file.
Otherwise,
a value of -1 is returned and
.IR errno
is set to indicate
the error.
.SH ERRORS
.BR Lseek
will fail and the file pointer will remain unchanged if:
.RS
.IP \fBEBADF\fR
.IR Fildes
is not an open file descriptor.
.IP \fBESPIPE\fR
.IR Fildes
is associated with a pipe, socket, or FIFO.
.IP \fBEINVAL\fR
.I Whence
is not a proper value.
.RE
.SH SEE ALSO
.BR dup (2),
.BR open (2)
.SH BUGS
In the GNO implementation, doing an
.BR lseek
past the end of file is permitted, but the created gap (as mentioned
above) is not gauranteed to contain bytes of zeros.
.LP
This document's use of
.I whence
is incorrect English, but is maintained for historical reasons.
.SH STANDARDS
The
.BR lseek
function
conforms to IEEE Std 1003.1-1988 (POSIX).

76
usr.man/man2/mkdir.2 Normal file
View File

@ -0,0 +1,76 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)mkdir.2 8.2 (Berkeley) 12/11/93
.\"
.TH MKDIR 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR mkdir
\- make a directory file
.SH SYNOPSIS
.nf
#include <sys/stat.h>
GNO: int \fBmkdir\fR (const char *\fIpath\fR);
POSIX: int \fBmkdir\fR (const char *\fIpath\fR, mode_t \fImode\fR);
.fi
.SH DESCRIPTION
The directory
.I path
is created with the access permissions specified by
.I mode
and restricted by the the
.BR umask (2)
of the calling process.
.LP
The directory's owner ID is set to the process's effective user ID.
The directory's group ID is set to that of the parent directory in
which it is created.
.SH RETURN VALUES
A 0 return value indicates success. A -1 return value
indicates an error, and an error code is stored in
.IR errno .
.SH BUGS
The GNO implementation does not take a
.IR mode
parameter. Attempting to provide one will cause stack errors.
The implementation should probably be changed to accept such a
parameter.
.SH SEE ALSO
.BR chmod (2),
.BR stat (2),
.BR umask (2)
.SH STANDARDS
Because of the missing
.IR mode
parameter in the GNO implementation,
.BR mkdir
does not conform to IEEE Std 1003.1-1988 (POSIX).

249
usr.man/man2/open.2 Normal file
View File

@ -0,0 +1,249 @@
.\" 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.
.\"
.\" @(#)open.2 8.2 (Berkeley) 11/16/93
.\"
.TH OPEN 2 "22 January 1997" GNO "System Calls"
.SH NAME
.BR open
\- open or create a file for reading or writing
.SH SYNOPSIS
#include <fcntl.h>
.sp 1
int
\fBopen\fR(const char *\fIpath\fR, int \fIflags\fR, ...);
.SH DESCRIPTION
The file name specified by
.I path
is opened
for reading and/or writing as specified by the
argument
.IR flags .
A third parameter,
.IR mode ,
(of type mode_t) must be specified if and only if the
.BR O_CREAT
flag is set. The
.BR O_CREAT
flag indicates that if the file doesn't exist it is to be created with mode
.I mode
as described in
.BR chmod (2)
and modified by the process' umask value (see
.BR umask (2)).
.LP
The flags specified are formed by the bitwise
.IR OR
of the following values:
.IP \fBO_RDONLY\fR
Open the file for reading only.
.IP \fBO_WRONLY\fR
Open the file for writing only.
An attempt to open a volume directory or subdirectory will fail.
.IP \fBO_RDWR\fR
Open the file for reading and writing.
An attempt to open a volume directory or subdirectory will fail.
.IP \fBO_APPEND\fR
Opening a file with
.BR O_APPEND
set causes the file pointer to be moved to the current end of file;
each write on the file will be appended to the end.
.IP \fBO_CREAT\fR
Create file if it does not exist.
.IP \fBO_TRUNC\fR
If
.BR O_TRUNC
is specified and the
file exists, the file is truncated to zero length.
.IP \fBO_EXCL\fR
If
.BR O_EXCL
is set with
.BR O_CREAT
and the file already
exists,
.BR open
returns an error. This may be used to
implement a simple exclusive access locking mechanism.
If
.BR O_EXCL
is set and the last component of the pathname is
a symbolic link,
.BR open
will fail even if the symbolic
link points to a non-existent name.
.IP \fBO_BINARY\fR
Files opened with the Orca/Shell
.BR open
call by default do newline translation unless the
.BR O_BINARY
flag is used. This implementation does no newline translation by
default (see
.BR O_TRANS ,
below). The
.BR O_BINARY
flag is ignored except that if it is set, the GS/OS file type of any
newly created file will be set to BIN rather than TXT.
.sp 1
The
.BR O_BINARY
flag is non-standard.
.IP \fBO_TRANS\fR
If the
.BR O_TRANS
flag has been set, then newline translation will occur on all
.BR read
and
.BR write
calls on the returned file descriptor: During
.BR write
calls, any LF (linefeed) character will be translated to
a CR (carridge return). During
.BR read
calls, the opposite translation occurs.
This is similar to, but opposite of, the
.BR O_BINARY
flag interpretation under the Orca/Shell.
.sp 1
The
.BR O_TRANS
flag is non-standard and has been included only to assist in
the porting of problem Unix programs. Note that files which
use the CR-LF pair (as is commonly found on MS-DOS platforms),
.I "will not"
have the character pair collapsed to (expanded from) a single character
during reads from (writes to) those files.
.IP \fBO_NONBLOCK\fR
If the
.BR O_NONBLOCK
flag is specified and the
.BR open
call would result
in the process being blocked for some reason (e.g., waiting for
carrier on a dialup line),
.BR open
returns immediately.
The first time the process attempts to perform I/O on the open
file it will block. (This feature is not currently implemented).
.IP \fBO_SHLOCK\fR
Atomically obtain a shared lock.
(This feature is not currently implemented under GNO.)
.IP \fBO_EXLOCK\fR
Atomically obtain an exclusive lock.
(This feature is not currently implemented under GNO.)
.LP
When opening a file, a lock with
.BR flock (2)
semantics can be obtained by setting
.BR O_SHLOCK
for a shared lock, or
.BR O_EXLOCK
for an exclusive lock.
If creating a file with
.BR O_CREAT ,
the request for the lock will never fail
(provided that the underlying filesystem supports locking).
.LP
If successful,
.BR open
returns a non-negative integer, termed a file descriptor.
It returns -1 and sets
.BR errno
on failure.
Unless
.BR O_APPEND
was specified, the file pointer used to mark the current position within the
file is set to the beginning of the file.
.LP
The new descriptor is set to remain open across
.BR execve
system calls; see
.BR close (2)
and
.BR fcntl (2).
.LP
The system imposes a limit on the number of file descriptors
open simultaneously by one process.
.BR getdtablesize (2)
returns the current system limit.
.SH COMPATIBILITY
Unlike the GNO implementation, the Orca/C
.BR open
call takes no optional third parameter.
.LP
The
.IR mode
parameter is normally expected to be in Unix mode format, although
this can be changed by the application. See
.BR mapMode (3).
.SH BUGS
Because
.BR umask (2)
is not yet implemented in the GNO kernel, it has no effect on the
.BR fopen (3)
or GS/OS
.BR OpenGS
calls. Consequently, the umask is not used in
.BR open (2),
either.
.LP
Due to the way the stack is maintained under Orca/C, it is an error to
provide the
.IR mode
parameter if the
.BR O_CREAT
flag is not set. Similarily, it is an error to omit
.IR mode
if
.BR O_CREATE
is set. Depending on how the calling routine was compiled, this error
will either manifest itself as a failed Orca/C runtime stack check, or
as a crash of the machine.
.LP
The flags
.BR O_NONBLOCK ,
.BR O_SHLOCK ,
and
.BR O_EXLOCK
are not currently implemented and will be ignored.
.SH SEE ALSO
.BR chmod (2),
.BR close (2),
.BR dup (2),
.BR getdtablesize (2),
.BR lseek (2),
.BR read (2),
.BR write (2),
.BR umask (2)
.SH HISTORY
An
.BR open
function call appeared in Version 6 AT&T UNIX.

130
usr.man/man2/pipe.2 Normal file
View File

@ -0,0 +1,130 @@
.\" 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.
.\"
.\" @(#)pipe.2 8.1 (Berkeley) 6/4/93
.\"
.TH PIPE 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR pipe
\- create descriptor pair for interprocess communication
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
int
\fBpipe\fR (int *\fIfildes\fR);
.SH DESCRIPTION
The
.BR pipe
function
creates a
.IR pipe ,
which is an object allowing
unidirectional data flow,
and allocates a pair of file descriptors.
The first descriptor connects to the
.IR read
end of the pipe,
and the second connects to the
.IR write
end, so that data written to
.I fildes[1]
appears on (i.e., can be read from)
.IR fildes[0] .
This allows the output of one program to be
sent
to another program:
The source's standard output is set up to be
the write end of the pipe,
and the sink's standard input is set up to be
the read end of the pipe.
The pipe itself persists until all its associated descriptors are
closed.
.LP
A pipe whose read or write end has been closed is considered
.IR widowed .
Writing on such a pipe causes the writing process to receive
a
.BR SIGPIPE
signal.
Widowing a pipe is the only way to deliver end-of-file to a reader:
after the reader consumes any buffered data, reading a widowed pipe
returns a zero count (end of file).
.SH LIMITS
Up to 4096 bytes of data are buffered before the writing process is
suspended. Should more than 4096 bytes be necessary in any pipe among
a loop of processes, deadlock will occur. This is not a limitation
specific to GNO but to multiprogramming in general.
.SH NOTES
This man page refers to the Unix
.BR read (2)
and
.BR write (2)
operations. On the IIgs, the described behavior refer to any system
calls doing I/O, including:
.RS
.nf
GS/OS ReadGS and WriteGS
TextTools calls
C stdio I/O routines
.fi
.RE
.SH RETURN VALUES
On successful creation of the pipe, zero is returned. Otherwise,
a value of -1 is returned and the variable
.IR errno
set to indicate the
error.
.SH ERRORS
The
.BR pipe
call will fail if:
.RS
.IP \fBEMFILE\fR
Too many descriptors are active.
.IP \fBENFILE\fR
The system file table is full.
.IP \fBEFAULT\fR
The
.I fildes
buffer is in an invalid area of the process's address
space.
.RE
.SH SEE ALSO
.BR sh (1),
.BR read (2),
.BR write (2),
.BR fork (2),
.BR socketpair (2)
.SH HISTORY
A
.BR pipe
function call appeared in Version 6 AT&T UNIX.

128
usr.man/man2/ports.2 Normal file
View File

@ -0,0 +1,128 @@
.\"
.\" $Id: ports.2,v 1.1 1997/02/27 07:32:14 gdr Exp $
.\"
.\" .TH "PORTS IPC" 2 GNO "System Calls" "16 December 1996"
.TH "PORTS IPC" 2 "16 December 1996" GNO "System Calls"
.SH NAME
.BR pbind ,
.BR pcreate ,
.BR pdelete ,
.BR pgetcount ,
.BR pgetport ,
.BR preceive ,
.BR preset ,
.BR psend
\- GNO ports IPC system
.SH SYNOPSIS
.nf
#include <sys/ports.h>
int pcreate (int \fIcount\fR);
int pbind (int \fIportid\fR, const char *\fIname\fR);
int pgetport (const char *\fIname\fR);
int psend (int \fIportid\fR, long \fImsg\fR);
long preceive (int \fIportid\fR);
int pdelete (int \fIportid\fR, int (*\fIdispose\fR)(long));
int preset (int \fIportid\fR, int (*\fIdispose\fR)(long));
int pgetcount (int \fIportid\fR);
.fi
.SH DESCRIPTION
The Ports IPC (interprocess communication) machanism 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 as the
.IR count
parameter of the
.BR pcreate
call.
.LP
Creation of a port is done with
.BR 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
the sending process.
.BR pcreate
returns a port ID value that must be used in subsequent calls to the Ports
IPC routines.
.LP
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
.BR pbind .
The
.IR name
argument may be any length, but only the first 32 characters are significant.
If a name has already been bound to the chosen
.IR portid ,
-1 is returned and
.BR errno
is set.
.LP
To get the
.IR portid
of a port by it's name, use the
.BR pgetport
call, with
.IR name
as the name of the port for which you wish to obtain the port ID.
If no port is associated with
.IR name ,
-1 is returned and errno is set. Names are only unbound from a port
when that port is deleted.
.LP
.BR 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
.BR pcreate
call), then the sending process blocks until a message is read from the
port. Messages are retrieved from a port using the
.BR preceie
call.
.BR pgetcount
returns the number of messages in the port that have not been received;
this may be used to avoid blocking on a
.BR psend
call.
.LP
If you wish to clear the contents of a port, (for example to synchronize
communication after an error condition), use the
.BR preset
call. The arguments to this call are the port ID and the address of a
.IR dispose
function. Each message in the port, before being cleared, is passed to the
.IR dispose
function so that appropriate clean-up actio nmay be taken on the data.
For example, if the messages correspond to the address of memory blocks
obtained with
.BR malloc (3),
you could pass
.BR free (3)
as
.IR dispose
to automatically deallocate that memory. If you don't wish to take any
special action on the data being cleared, pass the NULL pointer for the
.IR dispose
argument.
.LP
To destroy a port, make the
.BR pdelete
call. It accepts the same arguments as
.BR preset
and they operate as described above. The difference between
.BR preset
and
.BR pdelete
is that the latter totally destroys a port; it may no longer be used.
.BR preset
clears a ports data but leaves the port open for more data transmissions.
.SH EXAMPLES
For an example of the use of ports, see the source code to the print
spooling utilities,
.BR lpc (1),
.BR lpr (1),
.BR lpd (8),
and
.BR FilePort .
.SH "SEE ALSO"
.BR procsend (2).

60
usr.man/man2/procsend.2 Normal file
View File

@ -0,0 +1,60 @@
.\"
.\" $Id: procsend.2,v 1.1 1997/02/27 07:32:15 gdr Exp $
.\"
.\" .TH "MESSAGE IPC" 2 GNO "System Calls" "16 December 1996"
.TH "MESSAGE IPC" 2 "16 December 1996" GNO "System Calls"
.SH NAME
.BR procreceive ,
.BR procsend ,
.BR procrecvclr ,
.BR procrecvtim
\- GNO message passing IPC system
.SH SYNOPSIS
.nf
#include <gno/gno.h>
int procsend (pid_t \fIpid\fR, unsigned long \fImsg\fR);
unsigned long procreceive (void);
unsigned long procrecvtim (short \fItimeout\fR);
unsigned long procrecvclr (void);
.fi
.SH DESCRIPTION
These kernel traps comprise GNO's message passing IPC (interprocess
communication) system. Messages are unsigned 32-bit data values. A
process sends a message to another by using the
.BR procsend
call. You must specify the process ID of the recipient and the message
to pass.
.LP
The
.BR procreceive
trap receives a message. If no message has been sent to the process, the
process sleeps until a message arrives. A
.BR procreceive
that is interrupted by a signal will abort and return -1, with
.BR errno
set to
.BR EINTR .
.LP
.BR procrecvclr
is used to clear any pending message a process may have waiting.
.LP
.BR procrecvtim
is similar to
.BR procreceive ,
but takes a
.IR timeout
argument, specified in 1/10ths of a second. If no message has been
received in
.IR timeout
seconds,
.BR procrecvtim
fails and returns -1. The message buffer for a process is only one message
deep; any attempt to
.BR procsend
a message to a process that already has one queued will result in an error.
.LP
For an IPC system with a deeper queue, see the Ports IPC man page,
.BR ports (2).
.SH "SEE ALSO"
.BR ports (2).

191
usr.man/man2/read.2 Normal file
View File

@ -0,0 +1,191 @@
.\" 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.
.\"
.\" @(#)read.2 8.4 (Berkeley) 2/26/94
.\"
.TH READ 2 "23 January 1997" GNO "System Calls"
.SH NAME
.BR read ,
.BR readv
\- read input
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/uio.h>
.br
#include <unistd.h>
.sp 1
ssize_t
\fBread\fR (int \fId\fR, void *\fIbuf\fR, size_t \fInbytes\fR);
.sp 1
ssize_t
\fBreadv\fR (int \fId\fR, const struct iovec *\fIiov\fR, int \fIiovcnt\fR);
.SH DESCRIPTION
.BR read
attempts to read
.I nbytes
of data from the object referenced by the descriptor
.I d
into the buffer pointed to by
.IR buf .
.BR readv
performs the same action, but scatters the input data
into the
.I iovcnt
buffers specified by the members of the
.I iov
array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
.LP
For
.BR readv ,
the
.I iovec
structure is defined as:
.LP
.nf
struct iovec {
void *iov_base;
size_t iov_len;
};
.fi
.LP
Each
.I iovec
entry specifies the base address and length of an area
in memory where data should be placed.
.BR readv
will always fill an area completely before proceeding
to the next.
.LP
On objects capable of seeking, the
.BR read
starts at a position
given by the pointer associated with
.I d
(see
.BR lseek (2)).
Upon return from
.BR read ,
the pointer is incremented by the number of bytes actually read.
.LP
Objects that are not capable of seeking always read from the current
position. The value of the pointer associated with such an
object is undefined.
.LP
Upon successful completion,
.BR read
and
.BR readv
return the number of bytes actually read and placed in the buffer.
The system guarantees to read the number of bytes requested if
the descriptor references a normal file that has that many bytes left
before the end-of-file, but in no other case.
.LP
If the file was opened with the GNO-specific flag
.BR O_TRANS ,
then newline translation will occur; any carridge return character (0x0d)
read from descriptor
.I d
will be converted to a line feed (0x0a).
.SH RETURN VALUES
If successful, the
number of bytes actually read is returned. Upon reading end-of-file,
zero is returned.
Otherwise, a -1 is returned and the global variable
.IR errno
is set to indicate the error.
.SH ERRORS
.BR read
and
.BR readv
will succeed unless:
.RS
.IP \fBEBADF\fR
.I D
is not a valid file or socket descriptor open for reading.
.IP \fBEFAULT\fR
.I Buf
points outside the allocated address space.
.IP \fBEIO\fR
An I/O error occurred while reading from the file system.
.IP \fBEINTR\fR
A read from a slow device was interrupted before
any data arrived by the delivery of a signal.
.IP \fBEINVAL\fR
The pointer associated with
.I d
was negative.
.IP \fBEAGAIN\fR
The file was marked for non-blocking I/O,
and no data were ready to be read.
.RE
.LP
In addition,
.BR readv
may return one of the following errors:
.RS
.IP \fBEINVAL\fR
.I Iovcnt
was less than or equal to 0, or greater than 16.
.IP \fBEINVAL\fR
One of the
.I iov_len
values in the
.I iov
array was negative.
.IP \fBEINVAL\fR
The sum of the
.I iov_len
values in the
.I iov
array overflowed a 32-bit integer.
.RE
.SH SEE ALSO
.BR dup (2),
.BR fcntl (2),
.BR open (2),
.BR pipe (2),
.BR select (2),
.BR socket (2),
.BR socketpair (2)
.SH STANDARDS
.BR Read
is expected to conform to IEEE Std 1003.1-1988 (POSIX).
.SH HISTORY
The
.BR readv
function call
appeared in 4.2BSD.
A
.BR read
function call
appeared in
Version 6 AT&T UNIX.

279
usr.man/man2/recv.2 Normal file
View File

@ -0,0 +1,279 @@
.\" 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.
.\"
.\" @(#)recv.2 8.3 (Berkeley) 2/21/94
.\"
.TH RECV 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR recv ,
.BR recvfrom ,
.BR recvmsg
\- receive a message from a socket
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBrecv\fR
(int \fIs\fR, void *\fIbuf\fR, size_t \fIlen\fR, unsigned int \fIflags\fR);
.sp 1
int
\fBrecvfrom\fR
(int \fIs\fR, void *\fIbuf\fR, size_t \fIlen\fR, unsigned int \fIflags\fR,
struct sockaddr *\fIfrom\fR, int *\fIfromlen\fR);
.sp 1
int
\fBrecvmsg\fR
(int \fIs\fR, struct msghdr *\fImsg\fR, unsigned int \fIflags\fR);
.SH DESCRIPTION
.BR Recvfrom
and
.BR recvmsg
are used to receive messages from a socket,
and may be used to receive data on a socket whether or not
it is connection-oriented.
.LP
If
.I from
is non-NULL, and the socket is not connection-oriented,
the source address of the message is filled in.
.I Fromlen
is a value-result parameter, initialized to the size of
the buffer associated with
.IR from ,
and modified on return to indicate the actual size of the
address stored there.
.LP
The
.BR recv
call is normally used only on a
.IR connected
socket (see
.BR connect (2))
and is identical to
.BR recvfrom
with a NULL
.I from
parameter.
As it is redundant, it may not be supported in future releases.
.LP
All three routines return the length of the message on successful
completion.
If a message is too long to fit in the supplied buffer,
excess bytes may be discarded depending on the type of socket
the message is received from (see
.BR socket (2)).
.LP
If no messages are available at the socket, the
receive call waits for a message to arrive, unless
the socket is nonblocking (see
.BR fcntl (2))
in which case the value -1 is returned and the external variable
.IR errno
set to EAGAIN.
The receive calls normally return any data available,
up to the requested amount,
rather than waiting for receipt of the full amount requested;
this behavior is affected by the socket-level options
.BR SO_RCVLOWAT
and
.BR SO_RCVTIMEO
described in
.BR getsockopt (2).
.LP
The
.BR select (2)
call may be used to determine when more data arrive.
.LP
The
.I flags
argument to a recv call is formed by
.IR or 'ing
one or more of the values:
.RS
.TP
MSG_OOB
process out-of-band data
.TP
MSG_PEEK
peek at incoming message
.TP
MSG_WAITALL
wait for full request or error
.RE
.LP
The
.BR MSG_OOB
flag requests receipt of out-of-band data
that would not be received in the normal data stream.
Some protocols place expedited data at the head of the normal
data queue, and thus this flag cannot be used with such protocols.
The MSG_PEEK flag causes the receive operation to return data
from the beginning of the receive queue without removing that
data from the queue.
Thus, a subsequent receive call will return the same data.
The MSG_WAITALL flag requests that the operation block until
the full request is satisfied.
However, the call may still return less data than requested
if a signal is caught, an error or disconnect occurs,
or the next data to be received is of a different type than that returned.
.LP
The
.BR recvmsg
call uses a
.I msghdr
structure to minimize the number of directly supplied parameters.
This structure has the following form, as defined in <sys/socket.h>:
.nf
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
.fi
Here
.I msg_name
and
.I msg_namelen
specify the destination address if the socket is unconnected;
.I msg_name
may be given as a null pointer if no names are desired or required.
.I Msg_iov
and
.I msg_iovlen
describe scatter gather locations, as discussed in
.BR read (2).
.IR Msg_control ,
which has length
.IR msg_controllen ,
points to a buffer for other protocol control related messages
or other miscellaneous ancillary data.
The messages are of the form:
.nf
struct cmsghdr {
u_int cmsg_len; /* data byte count, including hdr */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by
u_char cmsg_data[]; */
};
.fi
As an example, one could use this to learn of changes in the data-stream
in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
a recvmsg with no data buffer provided immediately after an
.BR accept
call.
.LP
Open file descriptors are now passed as ancillary data for
.BR AF_UNIX
domain sockets, with
.I cmsg_level
set to
.BR SOL_SOCKET
and
.I cmsg_type
set to
.BR SCM_RIGHTS .
.LP
The
.I msg_flags
field is set on return according to the message received.
.BR MSG_EOR
indicates end-of-record;
the data returned completed a record (generally used with sockets of type
.BR SOCK_SEQPACKET ).
.BR MSG_TRUNC
indicates that
the trailing portion of a datagram was discarded because the datagram
was larger than the buffer supplied.
.BR MSG_CTRUNC
indicates that some
control data were discarded due to lack of space in the buffer
for ancillary data.
.BR MSG_OOB
is returned to indicate that expedited or out-of-band data were received.
.LP
.SH RETURN VALUES
These calls return the number of bytes received, or -1
if an error occurred.
.SH ERRORS
The calls fail if:
.RS
.IP \fBEBADF\fR
The argument
.I s
is an invalid descriptor.
.IP \fBENOTCONN\fR
The socket is associated with a connection-oriented protocol
and has not been connected (see
.BR connect (2)
and
.BR accept (2)).
.IP \fBENOTSOCK\fR
The argument
.I s
does not refer to a socket.
.IP \fBEAGAIN\fR
The socket is marked non-blocking, and the receive operation
would block, or
a receive timeout had been set,
and the timeout expired before data were received.
.IP \fBEINTR\fR
The receive was interrupted by delivery of a signal before
any data were available.
.IP \fBEFAULT\fR
The receive buffer pointer(s) point outside the process's
address space.
.RE
.SH CONVORMANCE
The GNO prototypes of these routines differ slightly from that of
4.4BSD.
.SH SEE ALSO
.BR fcntl (2),
.BR read (2),
.BR select (2),
.BR getsockopt (2),
.BR socket (2)
.SH HISTORY
The
.BR recvmsg
function call appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

188
usr.man/man2/select.2 Normal file
View File

@ -0,0 +1,188 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)select.2 8.2 (Berkeley) 3/25/94
.\"
.TH SELECT 2 "15 January 1997" GNO "System Calls"
.SH NAME
.BR select
\- synchronous I/O multiplexing
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/time.h>
.br
#include <unistd.h>
.sp 1
int
\fBselect\fR (int \fInfds\fR, fd_set *\fIreadfds\fR, fd_set *\fIwritefds\fR, fd_set *\fIexceptfds\fR, struct timeval *\fItimeout\fR);
.sp 1
.BR FD_SET
.RI "(int " fd ", fd_set &" fdset );
.br
.BR FD_CLR
.RI "(int " fd ", fd_set &" fdset );
.br
.BR FD_ISSET
.RI "(int " fd ", fd_set &" fdset );
.br
.BR FD_ZERO
.RI "(fd_set &" fdset );
.SH DESCRIPTION
.BR Select
examines the I/O descriptor sets whose addresses are passed in
.IR readfds ,
.IR writefds ,
and
.I exceptfds
to see if some of their descriptors
are ready for reading, are ready for writing, or have an exceptional
condition pending, respectively.
The first
.I nfds
descriptors are checked in each set;
i.e., the descriptors from 0 through
.RI ( nfds )
in the descriptor sets are examined.
On return,
.BR select
replaces the given descriptor sets
with subsets consisting of those descriptors that are ready
for the requested operation.
.BR Select
returns the total number of ready descriptors in all the sets.
.LP
The descriptor sets are stored as bit fields in arrays of integers.
The following macros are provided for manipulating such descriptor sets:
\fBFD_ZERO\fR(&\fIfdsetx\fR)
initializes a descriptor set
.I fdset
to the null set.
\fBFD_SET\fR(\fIfd\fR, &\fIfdset\fR)
includes a particular descriptor
.I fd
in
.IR fdset .
\fBFD_CLR\fR(\fIfd\fR, &\fIfdset\fR)
removes
.I fd
from
.IR fdset .
\fBFD_ISSET\fR(\fIfd\fR, &\fIfdset)\fR
is non-zero if
.I fd
is a member of
.IR fdset ,
zero otherwise.
The behavior of these macros is undefined if
a descriptor value is less than zero or greater than or equal to
.BR FD_SETSIZE ,
which is normally at least equal
to the maximum number of descriptors supported by the system.
.LP
If
.I timeout
is a non-NULL pointer, it specifies a maximum interval to wait for the
selection to complete. If
.I timeout
is a NULL pointer, the select blocks indefinitely. To affect a poll, the
.I timeout
argument should be non-NULL, pointing to a zero-valued timeval structure.
.LP
Any of
.IR readfds ,
.IR writefds ,
and
.I exceptfds
may be given as NULL pointers if no descriptors are of interest.
.SH RETURN VALUES
.BR Select
returns the number of ready descriptors that are contained in
the descriptor sets,
or -1 if an error occurred.
If the time limit expires,
.BR select
returns 0.
If
.BR select
returns with an error,
including one due to an interrupted call,
the descriptor sets will be unmodified.
.SH ERRORS
An error return from
.BR select
indicates:
.RS
.IP \fBEBADF\fR
One of the descriptor sets specified an invalid descriptor.
.IP \fBEINTR\fR
A signal was delivered before the time limit expired and
before any of the selected events occurred.
.IP \fBEINVAL\fR
The specified time limit is invalid. One of its components is
negative or too large.
.RE
.SH SEE ALSO
.BR accept (2),
.BR connect (2),
.BR getdtablesize (2),
.BR gettimeofday (2),
.BR read (2),
.BR recv (2),
.BR send (2),
.BR write (2),
.BR clocks (7)
.SH BUGS
Although the provision of
.BR getdtablesize (2)
was intended to allow user programs to be written independent
of the kernel limit on the number of open files, the dimension
of a sufficiently large bit field for select remains a problem.
The default size
.BR FD_SETSIZE
(currently 32 for GNO) is somewhat larger than
the current kernel limit to the number of open files.
Unlike BSD systems, under GNO it is not possible for sites to reconfigure
this limit since it requires recompilation of the kernel.
.LP
.BR Select
should probably return the time remaining from the original timeout,
if any, by modifying the time value in place.
This may be implemented in future versions of the system.
Thus, it is unwise to assume that the timeout value will be unmodified
by the
.BR select
call.
.SH HISTORY
The
.BR select
function call appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

88
usr.man/man2/semaphore.2 Normal file
View File

@ -0,0 +1,88 @@
.\"
.\" $Id: semaphore.2,v 1.1 1997/02/27 07:32:15 gdr Exp $
.\"
.TH SEMAPHORE 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR scount ,
.BR screate ,
.BR sdelete ,
.BR ssignal ,
.BR swait
\- semaphore operations
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int \fBscount\fR (int \fIsem\fR);
.br
int \fBscreate\fR (int \fIcount\fR);
.br
int \fBsdelete\fR (int \fIsem\fR);
.br
int \fBssignal\fR (int \fIsem\fR);
.br
int \fBswait\fR (int \fIsem\fR);
.SH DESCRIPTION
.BR screate
is used to allocate a semaphore from the kernel semapore manager.
Semaphores are the most basic form of interprocess communication (IPC),
and these routines provide the power necessary to solve a large number
of synchronization and communication problems. (See an Operating Systems
text).
.LP
The initial
.IR count
determines how many times
.BR swait
can be called before processes are blocked.
.IR count
must non-negative, and is usually set to 1.
.BR screate
returns a semaphore ID number as an integer. This ID must be used in
all the other semaphore calls.
.LP
.BR sdelete
releases the specified semaphore, and returns to a ready state all
processes that were blocked on that semaphore.
.LP
.BR swait
decrements the value of the semaphore (initially specified by
.IR count )
by one. If the semaphore count is less than zero, the process is blocked
and queued for release by
.BR ssignal .
This is what is traditionally referred to as a semaphore-down operation.
.LP
.BR ssignal
increments the semaphore count by one. If the semaphore count is less
than zero,
.BR ssignal
unblocks a process blocked on the semaphore.
The selection of the process to be unblocked is arbitrary; FIFO operation
is not guaranteed.
.LP
.BR scount
retuns the current value of the semaphore referred to by
.IR sem .
Note that depending on this value for synchronization can lead to race
conditions.
.SH "RETURN VALUE"
On success,
.BR screate
returns the semaphore identifier,
.BR scount
returns the semaphore value, and
.BR sdelete ,
.BR ssignal ,
and
.BR swait
return zero.
All functions return -1 and set
.BR errno
on failure.
.SH BUGS
There is currently no mechanism for deallocating semaphores that are
orphaned by abnormal process termination.
.SH HISTORY
These semaphore routines were designed for XINU, written by Douglas Comer.

187
usr.man/man2/send.2 Normal file
View File

@ -0,0 +1,187 @@
.\" Copyright (c) 1983, 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.
.\"
.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94
.\" $Id: send.2,v 1.1 1997/02/27 07:32:15 gdr Exp $
.\"
.TH SEND 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR send ,
.BR sendto ,
.BR sendmsg
\- send a message from a socket
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
\fBsend\fR (int \fIs\fR, const void *\fImsg\fR, size_t \fIlen\fR,
unsigned int \fIflags\fR);
.sp 1
int
\fBsendto\fR (int \fIs\fR, const void *\fImsg\fR, size_t \fIlen\fR,
int \fIflags\fR, const struct sockaddr *\fIto\fR, unsigned int \fItolen\fR);
.sp 1
int
\fBsendmsg\fR (int \fIs\fR, const struct msghdr *\fImsg\fR,
unsigned int \fIflags\fR);
.SH DESCRIPTION
.BR Send ,
.BR sendto ,
and
.BR sendmsg
are used to transmit a message to another socket.
.BR Send
may be used only when the socket is in a
.IR connected
state, while
.BR sendto
and
.BR sendmsg
may be used at any time.
.LP
The address of the target is given by
.I to
with
.I tolen
specifying its size.
The length of the message is given by
.RI ( len )
If the message is too long to pass atomically through the
underlying protocol, the error
EMSGSIZE
is returned, and
the message is not transmitted.
.LP
No indication of failure to deliver is implicit in a
.BR send .
Locally detected errors are indicated by a return value of -1.
.LP
If no messages space is available at the socket to hold
the message to be transmitted, then
.BR send
normally blocks, unless the socket has been placed in
non-blocking I/O mode.
The
.BR select (2)
call may be used to determine when it is possible to
send more data.
.LP
The
.I flags
parameter may include one or more of the following:
.nf
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
#define MSG_EOR 0x8 /* data completes record */
#define MSG_EOF 0x100 /* data completes transaction */
.fi
.LP
The flag
.BR MSG_OOB
is used to send
.I out-of-band
data on sockets that support this notion (e.g.
.BR SOCK_STREAM ) ;
the underlying protocol must also support
.I out-of-band
data.
.BR MSG_EOR
is used to indicate a record mark for protocols which support the
concept.
.BR MSG_EOF
requests that the sender side of a socket be shut down, and that an
appropriate indication be sent at the end of the specified data;
this flag is only implemented for
.BR SOCK_STREAM
sockets in the
.BR PF_INET
protocol family, and is used to implement Transaction TCP (see
.BR ttcp (4)).
.BR MSG_DONTROUTE
is usually used only by diagnostic or routing programs.
.LP
See
.BR recv (2)
for a description of the
.I msghdr
structure.
.SH RETURN VALUES
The call returns the number of characters sent, or -1
if an error occurred.
.SH ERRORS
.BR Send ,
.BR sendto ,
and
.BR sendmsg
fail if:
.RS
.IP \fBEBADF\fR
An invalid descriptor was specified.
.IP \fBENOTSOCK\fR
The argument
.I s
is not a socket.
.IP \fBEFAULT\fR
An invalid user space address was specified for a parameter.
.IP \fBEMSGSIZE\fR
The socket requires that message be sent atomically,
and the size of the message to be sent made this impossible.
.IP \fBEAGAIN\fR
The socket is marked non-blocking and the requested operation
would block.
.IP \fBENOBUFS\fR
The system was unable to allocate an internal buffer.
The operation may succeed when buffers become available.
.IP \fBENOBUFS\fR
The output queue for a network interface was full.
This generally indicates that the interface has stopped sending,
but may be caused by transient congestion.
.RE
.SH CONVORMANCE
The GNO prototypes of these routines differ slightly from that of
4.4BSD.
.SH SEE ALSO
.BR fcntl (2),
.BR recv (2),
.BR select (2),
.BR getsockopt (2),
.BR socket (2),
.BR write (2)
.SH HISTORY
The
.BR sendmsg
function call appeared in 4.2BSD.
The first appearance in GNO was in v2.0.5.

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

@ -0,0 +1,85 @@
.\"
.\" $Id: setdebug.2,v 1.1 1997/02/27 07:32:15 gdr Exp $
.\"
.TH SETDEBUG 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR setdebug
\- set kernel debugging output options
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int
\fBsetdebug\fR(int \fIoptions\fR);
.SH DESCRIPTION
.BR setdebug
enables and disables various debugging routines built into the kernel.
The routines display useful debugging information to standard error (except
for
.BR dbgSIG ,
see BUGS). Debug output is enabled by setting the corresponding bit in
.IR options ,
according to the following table. To turn off all debugging output,
.IR options
should be set to zero. The various debug options are #defined in
<gno/gno.h>.
.IP \fBdbgGSOS\fR
When this bit is set, call numbers will be printed out for 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.
.IP \fBdbgPATH\fR
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:
.nf
EP: <fullpath>
.fi
.IP \fBdbgERROR\fR
For every GS/OS call that is made, if an error occurs the error code is
printed in inverse lettering in hexadecimal 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
.BR dbgGSOS
is also enabled.
.IP \fBdbgSIG\fR
This flag enables signal tracing. Each time a signal is sent, whether by
.BR kill (2),
job control, or keyboard, the signal number and target process is displayed.
The format is:
.nf
kill (-\fIsignum\fR): \fIpid\fR: \fItpid\fR
.fi
.IP \fBdbgSYSCALL\fR
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
.BR _execve (2),
.BR fork (2),
.BR settpgrp (2),
.BR tcnewpgrp (2),
and
.BR tctpgrp (2).
.IP \fBdbgPBLOCK\fR
The memory addresses of GS/OS and ORCA/Shell parameter parameter blocks
are printed for each call. As with
.BR dbgERROR ,
this option has no effect unless
.BR dbgGSOS
is also enabled.
.SH RETURN VALUE
.BR setdebug
returns the previous value of the debug
.IR options
word.
.SH BUGS
Due to problems associated with signals that are sent during process
termination,
.BR dgbSIG
prints its information to standard output instead of standard error.
.SH SEE ALSO
fork (2),
execve (2),
ioctl (2),
kill (2)

88
usr.man/man2/setpgid.2 Normal file
View File

@ -0,0 +1,88 @@
.\" 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.
.\"
.\" @(#)setpgid.2 8.1 (Berkeley) 6/4/93
.\"
.TH SETPGID 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR setpgid ,
.BR setpgrp
\- set process group
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
int
\fBsetpgid\fR (pid_t \fIpid\fR, pid_t \fIpgrp\fR);
.br
int
\fBsetpgrp\fR (pid_t \fIpid\fR, pid_t \fIpgrp\fR);
.SH DESCRIPTION
.BR Setpgid
sets the process group of the specified process
.BR pid
to the specified
.BR pgrp .
If
.BR pid
is zero, then the call applies to the current process.
.LP
If the invoker is not the super-user, then the affected process
must have the same effective user-id as the invoker or be a descendant
of the invoking process.
.SH RETURN VALUES
.BR Setpgid
returns 0 when the operation was successful.
If the request failed, -1 is returned and the global variable
.IR errno
indicates the reason.
.SH ERRORS
.BR Setpgid
will fail and the process group will not be altered if:
.RS
.IP \fBESRCH\fR
The requested process does not exist.
.IP \fBEPERM\fR
The effective user ID of the requested process is different
from that of the caller and the process is not a descendent
of the calling process.
.RE
.SH SEE ALSO
.BR getpgrp (2)
.SH STANDARDS
.BR Setpgid
conforms to IEEE Std 1003.1-1988 (POSIX).
.SH COMPATIBILITY
.BR Setpgrp
is identical to
.BR setpgid ,
and is retained for calling convention compatibility with historical
versions of BSD.

90
usr.man/man2/setregid.2 Normal file
View File

@ -0,0 +1,90 @@
.\" 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.
.\"
.\" @(#)setregid.2 8.2 (Berkeley) 4/16/94
.\"
.TH SETREGID 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR setregid
\- set real and effective group ID
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
int
\fBsetregid\fR (gid_t \fIrgid\fR, gid_t \fIegid\fR);
.SH DESCRIPTION
The real and effective group ID's of the current process
are set to the arguments.
Unprivileged users may change the real group
ID to the effective group ID and vice-versa; only the super-user may
make other changes.
.LP
Supplying a value of -1 for either the real or effective
group ID forces the system to substitute the current
ID in place of the -1 parameter.
.LP
The
.BR setregid
function was intended to allow swapping
the real and effective group IDs
in set-group-ID programs to temporarily relinquish the set-group-ID value.
This function did not work correctly,
and its purpose is now better served by the use of the
.BR setegid
function (see
.BR setuid (2)).
.LP
When setting the real and effective group IDs to the same value,
the standard
.BR setgid
function is preferred.
.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 ERRORS
.RS
.IP \fBEPERM\fR
The current process is not the super-user and a change
other than changing the effective group-id to the real group-id
was specified.
.RE
.SH SEE ALSO
.BR getgid (2),
.BR setegid (2),
.BR setgid (2),
.BR setuid (2)
.SH HISTORY
The
.BR setregid
system call appeared in 4.2BSD.

88
usr.man/man2/setreuid.2 Normal file
View File

@ -0,0 +1,88 @@
.\" 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.
.\"
.\" @(#)setreuid.2 8.2 (Berkeley) 4/16/94
.\"
.TH SETREUID 2 "16 January 1996" GNO "System Calls"
.SH NAME
.BR setreuid
\- set real and effective user ID
.SH SYNOPSIS
.br
#include <unistd.h>
.sp 1
int
\fBsetreuid\fR (uid_t \fIruid\fR, uid_t \fIeuid\fR);
.SH DESCRIPTION
The real and effective user IDs of the
current process are set according to the arguments.
If
.I ruid
or
.I euid
is -1, the current uid is filled in by the system.
Unprivileged users may change the real user
ID to the effective user ID and vice-versa; only the super-user may
make other changes.
.LP
The
.BR setreuid
function has been used to swap the real and effective user IDs
in set-user-ID programs to temporarily relinquish the set-user-ID value.
This purpose is now better served by the use of the
.BR seteuid
function (see
.BR setuid (2)).
.LP
When setting the real and effective user IDs to the same value,
the standard
.BR setuid
function is preferred.
.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 ERRORS
.RS
.IP \fBEPERM\fR
The current process is not the super-user and a change
other than changing the effective user-id to the real user-id
was specified.
.RE
.SH SEE ALSO
.BR getuid (2),
.BR seteuid (2),
.BR setuid (2)
.SH HISTORY
The
.BR setreuid
system call appeared in 4.2BSD.

83
usr.man/man2/setruid.2 Normal file
View File

@ -0,0 +1,83 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)setruid.3 8.1 (Berkeley) 6/2/93
.\"
.TH SETRUID 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR setruid ,
.BR setrgid
\- set user and group ID
.SH SYNOPSIS
.br
#include <sys/types.h>
.br
#include <unistd.h>
.sp 1
int
\fBsetruid\fR (uid_t \fIruid\fR);
.br
int
\fBsetrgid\fR (gid_t \fIrgid\fR);
.SH DESCRIPTION
The
.BR setruid
function
sets the real user ID of the current process.
.LP
The
.BR setrgid
function
sets the real group ID of the current process.
.SH RETURN VALUES
Upon success, these functions return 0;
otherwise \-1 is returned.
.LP
If the user is not the super user, or the uid
specified is not the real or effective ID, these
functions return \-1.
.LP
The use of these calls is not portable.
Their use is discouraged; they will be removed in the future.
.SH SEE ALSO
.BR setuid (2),
.BR setgid (2),
.BR seteuid (2),
.BR setegid (2),
.BR getuid (2),
.BR getgid (2)
.SH HISTORY
The
.BR setruid
and
.BR setrgid
syscalls appeared in 4.2 BSD
and were dropped in 4.4BSD.

120
usr.man/man2/setuid.2 Normal file
View File

@ -0,0 +1,120 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)setuid.2 8.1 (Berkeley) 6/4/93
.\"
.TH SETUID 2 "16 January 1996" GNO "System Calls"
.SH NAME
.BR setuid ,
.BR seteuid ,
.BR setgid ,
.BR setegid ,
\- set user and group ID
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <unistd.h>
.sp 1
int
\fBsetuid\fR (uid_t \fIuid\fR);
.br
int
\fBseteuid\fR (uid_t \fIeuid\fR);
.br
int
\fBsetgid\fR (gid_t \fIgid\fR);
.br
int
\fBsetegid\fR (gid_t \fIegid\fR);
.SH DESCRIPTION
The
.BR setuid
function
sets the real and effective
user IDs and the saved set-user-ID of the current process
to the specified value.
The
.BR setuid
function is permitted if the specified ID is equal to the real user ID
of the process, or if the effective user ID is that of the super user.
.LP
The
.BR setgid
function
sets the real and effective
group IDs and the saved set-group-ID of the current process
to the specified value.
The
.BR setgid
function is permitted if the specified ID is equal to the real group ID
of the process, or if the effective user ID is that of the super user.
.LP
The
.BR seteuid
function
sets the effective user ID (group ID) of the
current process.
The effective user ID may be set to the value
of the real user ID or the saved set-user-ID (see
.BR intro (2)
and
.BR execve (2));
in this way, the effective user ID of a set-user-ID executable
may be toggled by switching to the real user ID, then re-enabled
by reverting to the set-user-ID value.
Similarly, the effective group ID may be set to the value
of the real group ID or the saved set-user-ID.
.LP
.SH RETURN VALUES
Upon success, these functions return 0;
otherwise \-1 is returned.
.LP
If the user is not the super user, or the uid
specified is not the real, effective ID, or saved ID,
these functions return \-1.
.SH SEE ALSO
.BR getuid (2),
.BR getgid (2)
.SH STANDARDS
The
.BR setuid
and
.BR setgid
functions are compliant with the
POSIX 1003.1-88
specification with _POSIX_SAVED_IDS not defined.
The
.BR seteuid
and
.BR setegid
functions are extensions based on the POSIX
concept of _POSIX_SAVED_IDS,
and have been proposed for a future revision of the standard.

80
usr.man/man2/shutdown.2 Normal file
View File

@ -0,0 +1,80 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)shutdown.2 8.1 (Berkeley) 6/4/93
.\"
.TH SHUTDOWN 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR shutdown
\- shut down part of a full-duplex connection
.SH SYNOPSIS
.br
#include <sys/socket.h>
.sp 1
int
\fBshutdown\fR (int \fIs\fR, int \fIhow\fR);
.SH DESCRIPTION
The
.BR shutdown
call causes all or part of a full-duplex connection on
the socket associated with
.I s
to be shut down.
If
.I how
is 0, further receives will be disallowed.
If
.I how
is 1, further sends will be disallowed.
If
.I how
is 2, further sends and receives will be disallowed.
.SH DIAGNOSTICS
A 0 is returned if the call succeeds, -1 if it fails.
.SH ERRORS
The call succeeds unless:
.RS
.IP \fBEBADF\fR
.I S
is not a valid descriptor.
.IP \fBENOTSOCK\fR
.I S
is a file, not a socket.
.IP \fBENOTCONN\fR
The specified socket is not connected.
.RE
.SH SEE ALSO
.BR connect (2),
.BR socket (2)
.SH HISTORY
The
.BR shutdown
function call appeared in 4.2BSD.

56
usr.man/man2/sigblock.2 Normal file
View File

@ -0,0 +1,56 @@
.\"
.\" $Id: sigblock.2,v 1.1 1997/02/27 07:32:16 gdr Exp $
.\"
.TH SIGBLOCK 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR sigblock,
.BR sigmask
\- temporarily block signals
.SH SYNOPSIS
#include <signal.h>
.sp 1
long
\fBsigblock\fR(long \fImask\fR);
.br
#define \fBsigmask\fR(\fIsignum\fR)
.SH DESCRIPTION
.BR sigblock
is used ot temporarily block the reception of signals. The input parameter
.IR mask
is a bit vector that specifies which signals are to be blocked; a 1 in bit
.I n
will block signal
.IR n +1.
The
.IR mask
is bitwise-or'd with the current signal mask to create the new
signal mask.
.LP
.BR sigmask
is a macro that can be used to calculate signal masks for
.BR sigsetmask .
It takes a signal number
.IR signum ,
as listed in
.BR signal (2),
as an argument and returns a mask corresponding to that signal.
.LP
If a signal is sent to a process but is blocked, the event is recorded
for later release by
.BR sigsetmask (2).
blocked signals are not stacked; further occurrences of a blocked signal
will overwrite any previous pending signal of the same
.IR signum .
.LP
It is not possible to block
.BR SIGKILL ,
.BR SIGCONT ,
or
.BR SIGSTOP .
This restriction is silently enforced by the kernel.
.SH RETURN VALUE
The previous value of the signal mask is returned.
.SH SEE ALSO
.BR kill (2),
.BR sigsetmask (2),
.BR signal (2)

237
usr.man/man2/signal.2 Normal file
View File

@ -0,0 +1,237 @@
.\" 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.
.\"
.\" @(#)signal.3 8.3 (Berkeley) 4/19/94
.\"
.TH SIGNAL 3 "19 January 1997" GNO "System Calls"
.SH NAME
.BR signal
\- simplified software signal facilities
.SH SYNOPSIS
.br
#include <signal.h>
.sp 1
void (*\fBsignal\fR (int \fIsig\fR, void (*\fIfunc\fR)(int, int)))(int, int);
.sp 1
or in GNO's equivalent but easier to read typedef'd version:
.sp 1
typedef void (*sig_t) (int, int)
.sp 1
sig_t
\fBsignal\fR(int \fIsig\fR, sig_t \fIfunc\fR);
.SH DESCRIPTION
Signals allow the manipulation of a process from outside its
domain as well as allowing the process to manipulate itself or
copies of itself (children). There are two general types of signals:
those that cause termination of a process and those that do not.
Signals which cause termination of a program might result from
an irrecoverable error or might be the result of a user at a terminal
typing the `interrupt' character.
Signals are used when a process is stopped because it wishes to access
its control terminal while in the background (see
.BR tty (4)).
Signals are optionally generated
when a process resumes after being stopped,
when the status of child processes changes,
or when input is ready at the control terminal.
.LP
Most signals result in the termination of the process receiving them
if no action
is taken; some signals instead cause the process receiving them
to be stopped, or are simply discarded if the process has not
requested otherwise.
The
.BR signal
function allows for a signal to be caught, to be ignored, or to generate
an interrupt, except for
.BR SIGCONT
(which cannot be blocked), and
.BR SIGKILL
and
.BR SIGSTOP
(which cannot be caught, blocked, or ignored).
.LP
These signals are defined in the file <signal.h>:
.RS
.nf
Name Default Action Description
SIGHUP termination terminal line hangup
SIGINT termination interrupt program
SIGQUIT termination quit program
SIGILL termination illegal instruction
SIGTRAP termination trace trap
SIGABRT termination abort (generated by \fBabort\fR(3))
SIGEMT termination emulator trap
SIGFPE termination arithmetic exception
SIGKILL termination kill program
SIGBUS termination bus error
SIGSEGV termination segmentation fault
SIGSYS termination bad argument to system call
SIGPIPE termination write on a socket with no readers
SIGALRM termination real-time timer expired
SIGTERM termination software termination
SIGURG discarded urgent condition present on socket
SIGSTOP stop stop
SIGTSTP stop stop signal from keyboard
SIGCONT discarded continue after stop
SIGCHLD discarded child status has changed
SIGCLD discarded SYSV name for SIGCHLD
SIGTTIN stop background read attempted
SIGTTOU stop background write attempted
SIGIO discarded input/output possible on a file descriptor
SIGPOLL discarded SYSV name for SIGIO
SIGXCPU termination exceeded CPU time limit
SIGUSR1 termination user defined signal 1
SIGUSR2 termination user defined signal 2
.fi
.RE
.LP
The
.I func
procedure allows a user to choose the action upon receipt of a signal.
To set the default action of the signal to occur as listed above,
.I func
should be
.BR SIG_DFL .
A
.BR SIG_DFL
resets the default action.
To ignore the signal
.I func
should be
.BR SIG_IGN .
This will cause subsequent instances of the signal to be ignored
and pending instances to be discarded. If
.BR SIG_IGN
is not used,
further occurrences of the signal are
automatically blocked and
.I func
is called.
.LP
The handled signal is unblocked with the
function returns and
the process continues from where it left off when the signal occurred.
\fIUnlike previous Unix signal facilities, the handler
func() remains installed after a signal has been delivered.\fR
This behavior remains unchanged from GNO v2.0.4.
.LP
For some system calls, if a signal is caught while the call is
executing and the call is prematurely terminated,
the call is automatically restarted.
The affected system calls include
.BR read (2),
.BR write (2),
.BR sendto (2),
.BR recvfrom (2),
.BR sendmsg (2)
and
.BR recvmsg (2)
on a communications channel or a low speed device
and during a
.BR ioctl (2)
or
.BR wait (2).
However, calls that have already committed are not restarted,
but instead return a partial success (for example, a short read count).
.LP
When a process which has installed signal handlers forks,
the child process inherits the signals.
All caught signals will be reset to their default action by a call
to one of the
.BR execve (2)
family of functions;
ignored signals remain ignored.
.SH NOTES
As can be surmised from the prototype above,
.IR func
should be defined as follows:
.RS
.sp 1
void \fIfunc\fR(int \fIsig\fR, int \fIcode\fR)
.sp 1
.RE
.I sig
is the signal that will invoke the handler, and
.I code
is additional information about the interrupt condition. Currently,
.I code
is always zero. The handler should probably also be compiled using the
.B "#pragma databank 1"
directive, in the event
.I func
is not in the same bank as the C global data segment
.RI ( func
is called with the data bank equal to the program bank).
.LP
Orca/C already provides a
.BR signal
function, but it doesn't do very much. GNO's <signal.h> file replaces
the one that comes with Orca/C.
.SH RETURN VALUES
The previous action is returned on a successful call.
Otherwise, \-1 is returned and the global variable
.IR errno
is set to indicate the error.
.SH ERRORS
.BR Signal
will fail and no action will take place if one of the
following occur:
.RS
.IP \fBEINVAL\fR
.IR Sig
is not a valid signal number.
.IP \fBEINVAL\fR
An attempt is made to ignore or supply a handler for
.BR SIGKILL
or
.BR SIGSTOP .
.IP \fBEINVAL\fR
An attempt is made to ignore
.BR SIGCONT
(by default
.BR SIGCONT
is ignored).
.SH SEE ALSO
.BR kill (1),
.BR execve (2),
.BR fork (2),
.BR kill (2),
.BR sigblock (2),
.BR sigsetmask (2),
.BR wait (2),
.BR tty (4)
.SH HISTORY
A
.BR signal
facility appeared in 4.0BSD.

39
usr.man/man2/sigpause.2 Normal file
View File

@ -0,0 +1,39 @@
.\"
.\" $Id: sigpause.2,v 1.1 1997/02/27 07:32:16 gdr Exp $
.\"
.TH SIGPAUSE 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR sigpause
\- suspend process until a signal arrives
.SH SYNOPSIS
#include <signal.h>
.sp 1
int
\fBsigpause\fR(long int \fImask\fR);
.SH DESCRIPTION
.BR sigpause
suspends execution of the calling process until a signal arrives. The
.IR mask
parameter is assigned to the set of blocked signals (see
.BR sigsetmask (2)),
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
.IR mask
is zero to pause until any signal arrives.
.LP
.BR 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 occurance of that signal are then
manipulated, code is executed, etc. To end the critical section and
wait for more work, sigpause is called.
.SH RETURN VALUE
.BR sigpause
always returns an error (-1) and sets
.BR errno
to EINTR.
.SH SEE ALSO
.BR signal (2),
.BR sigblock (2),
.BR sigsetmask (2)

50
usr.man/man2/sigsetmask.2 Normal file
View File

@ -0,0 +1,50 @@
.\"
.\" $Id: sigsetmask.2,v 1.1 1997/02/27 07:32:16 gdr Exp $
.\"
.TH SIGSETMASK 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR sigsetmask
\- set signal mask
.SH SYNOPSIS
#include <signal.h>
.sp 1
long
\fBsigsetmask\fR(long \fImask\fR);
.br
#define \fBsigmask\fR(\fIsignum\fR)
.SH DESCRIPTION
.BR sigsetmask
is usually used to restore signal masks after modifications by
.BR sigblock .
The parameter mask is the absolute value to which the process signal
mask will be set. (Compare to
.BR sigblock ,
which adds the argument to the set of blocked signals.)
.LP
If there are pending instances of signals which become unblocked by the
.BR 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 in interrupt handlers).
.LP
.BR sigmask
is a macro that can be used to calculate signal masks for
.BR sigsetmask .
It takes a signal number, as listed in
.BR signal (2),
as an argument and returns a mask corresponding to that signal.
.SH "RETURN VALUE"
The previous value of the signal mask is returned from
.BR sigsetmask .
.SH CAVEATS
If somehow the process re-blocks a signal released by
.BR 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
.BR sigblock
call.
.SH SEE ALSO
.BR kill (2),
.BR sigblock (2),
.BR signal (2)

270
usr.man/man2/socket.2 Normal file
View File

@ -0,0 +1,270 @@
.\" Copyright (c) 1983, 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.
.\"
.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93
.\" $Id: socket.2,v 1.1 1997/02/27 07:32:16 gdr Exp $
.\"
.TH SOCKET 2 "February 15, 1995" "BSD 4.2" "System Calls"
.SH NAME
.BR socket
\- create an endpoint for communication
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/socket.h>
.sp 1
int
socket (int domain, int type, int protocol);
.SH DESCRIPTION
.BR Socket
creates an endpoint for communication and returns a descriptor.
.LP
The
.I domain
parameter specifies a communications domain within which
communication will take place; this selects the protocol family
which should be used.
These families are defined in the include file <sys/socket.h>
The currently understood formats are
.LP
.RS
.nf
PF_LOCAL (Host-internal protocols, formerly called PF_UNIX),
PF_INET (ARPA Internet protocols),
PF_ISO (ISO protocols),
PF_CCITT (ITU-T protocols, like X.25), and
PF_NS (Xerox Network Systems protocols).
.fi
.RE
.LP
The socket has the indicated
.IR type ,
which specifies the semantics of communication. Currently
defined types are:
.LP
.RS
.nf
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
.fi
.RE
.LP
A
.BR SOCK_STREAM
type provides sequenced, reliable,
two-way connection based byte streams.
An out-of-band data transmission mechanism may be supported.
A
.BR SOCK_DGRAM
socket supports
datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length).
A
.BR SOCK_SEQPACKET
socket may provide a sequenced, reliable,
two-way connection-based data transmission path for datagrams
of fixed maximum length; a consumer may be required to read
an entire packet with each read system call.
This facility is protocol specific, and presently implemented
only for
.BR PF_NS .
.BR SOCK_RAW
sockets provide access to internal network protocols and interfaces.
The types
.BR SOCK_RAW ,
which is available only to the super-user, and
.BR SOCK_RDM ,
which is planned,
but not yet implemented, are not described here.
.LP
The
.I protocol
specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular
socket type within a given protocol family. However, it is possible
that many protocols may exist, in which case a particular protocol
must be specified in this manner. The protocol number to use is
particular to the \*(lqcommunication domain\*(rq in which communication
is to take place; see
.BR protocols (5).
.LP
Sockets of type
.BR SOCK_STREAM
are full-duplex byte streams, similar
to pipes. A stream socket must be in a
.IR connected
state before any data may be sent or received
on it. A connection to another socket is created with a
.BR connect (2)
call.
Once connected, data may be transferred using
.BR read (2)
and
.BR write (2)
calls or some variant of the
.BR send (2)
and
.BR recv (2)
calls.
(Some protocol families, such as the Internet family,
support the notion of an
.Dq implied connect,
which permits data to be sent piggybacked onto a connect operation by
using the
.BR sendto (2)
call.)
When a session has been completed a
.BR close (2)
may be performed.
Out-of-band data may also be transmitted as described in
.BR send (2)
and received as described in
.BR recv (2).
.LP
The communications protocols used to implement a
.BR SOCK_STREAM
insure that data
is not lost or duplicated. If a piece of data for which the
peer protocol has buffer space cannot be successfully transmitted
within a reasonable length of time, then
the connection is considered broken and calls
will indicate an error with -1 returns and with
.BR ETIMEDOUT
as the specific code
in the global variable
.IR errno .
The protocols optionally keep sockets
.Dq warm
by forcing transmissions
roughly every minute in the absence of other activity.
An error is then indicated if no response can be
elicited on an otherwise
idle connection for a extended period (e.g. 5 minutes).
A
.BR SIGPIPE
signal is raised if a process sends
on a broken stream; this causes naive processes,
which do not handle the signal, to exit.
.LP
.BR SOCK_SEQPACKET
sockets employ the same system calls
as
.BR SOCK_STREAM
sockets. The only difference
is that
.BR read (2)
calls will return only the amount of data requested,
and any remaining in the arriving packet will be discarded.
.LP
.BR SOCK_DGRAM
and
.BR SOCK_RAW
sockets allow sending of datagrams to correspondents
named in
.BR send (2)
calls. Datagrams are generally received with
.BR recvfrom (2),
which returns the next datagram with its return address.
.LP
An
.BR fcntl (2)
call can be used to specify a process group to receive
a
.BR SIGURG
signal when the out-of-band data arrives.
It may also enable non-blocking I/O
and asynchronous notification of I/O events
via
.BR SIGIO .
.LP
The operation of sockets is controlled by socket level
.IR options .
These options are defined in the file
.Ao Pa sys/socket.h Ac .
.BR Setsockopt (2)
and
.BR getsockopt (2)
are used to set and get options, respectively.
.SH RETURN VALUES
A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
.SH ERRORS
The
.BR socket
call fails if:
.RS
.IP \fBEPROTONOSUPPORT\fR
The protocol type or the specified protocol is not supported
within this domain.
.IP \fBEMFILE\fR
The per-process descriptor table is full.
.IP \fBENFILE\fR
The system file table is full.
.IP \fBEACCESS\fR
Permission to create a socket of the specified type and/or protocol
is denied.
.IP \fBENOBUFS\fR
Insufficient buffer space is available.
The socket cannot be created until sufficient resources are freed.
.RE
.SH SEE ALSO
.BR accept (2),
.BR bind (2),
.BR connect (2),
.BR getprotoent (3),
.BR getsockname (2),
.BR getsockopt (2),
.BR ioctl (2),
.BR listen (2),
.BR read (2),
.BR recv (2),
.BR select (2),
.BR send (2),
.BR shutdown (2),
.BR socketpair (2),
.BR write (2)
.RS
.LP
.I "An Introductory 4.3 BSD Interprocess Communication Tutorial"
.B PS1
volume 7
.LP
.I "BSD Interprocess Communication Tutorial"
.B PS1
volume 8
.RE
.SH HISTORY
The
.BR socket
function call appeared in 4.2BSD.

238
usr.man/man2/stat.2 Normal file
View File

@ -0,0 +1,238 @@
.\" 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.
.\"
.\" @(#)stat.2 8.3 (Berkeley) 4/19/94
.\"
.TH STAT 2 "19 January 1997" "BSD 4" "System Calls"
.SH NAME
.BR stat ,
.BR lstat ,
.BR fstat
\- get file status
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/stat.h>
.sp 1
int
\fBstat\fR (const char *\fIpath\fR, struct stat *\fIsb\fR);
.br
int
\fBlstat\fR (const char *\fIpath\fR, struct stat *\fIsb\fR);
.br
int
\fBfstat\fR (int \fIfd\fR, struct stat *\fIsb\fR);
.SH DESCRIPTION
These calls are used to retrieve status information about files.
They do much the same think as the GS/OS call
.BR GetFileInfoGS ,
except that they return the information in a format compatible with
Unix's
.BR stat
calls, and also provide information about sockets and GNO character
devices.
.LP
The
.BR stat
function obtains information about the file pointed to by
.IR path .
Read, write or execute
permission of the named file is not required, but all directories
listed in the path name leading to the file must be searchable.
.LP
.BR lstat
is like
.BR stat
except in the case where the named file is a symbolic link,
in which case
.BR lstat
returns information about the link,
while
.BR stat
returns information about the file the link references.
Unlike other filesystem objects,
symbolic links do not have an owner, group, access mode, times, etc.
Instead, these attributes are taken from the directory that
contains the link.
The only attributes returned from an
.BR lstat
that refer to the symbolic link itself are the file type (S_IFLNK),
size, blocks, and link count (always 1).
.LP
The
.BR fstat
obtains the same information about an open file
known by the file descriptor
.IR fd .
.LP
The
.I sb
argument is a pointer to a
.BR stat
structure
as defined by <sys/stat.h>
(shown below)
and into which information is placed concerning the file.
.nf
struct stat {
dev_t st_dev; /* device inode resides on */
ino_t st_ino; /* inode's number */
mode_t st_mode; /* inode protection mode */
nlink_t st_nlink; /* number or hard links to the file */
uid_t st_uid; /* user-id of owner */
gid_t st_gid; /* group-id of owner */
dev_t st_rdev; /* device type, for special file inode */
off_t st_size; /* file size, in bytes */
time_t st_atime; /* time of last access (GNO: same as st_mtime) */
int st_spare1; /* reserved */
time_t st_mtime; /* time of last data modification */
int st_spare2; /* reserved */
time_t st_ctime; /* time of last file status change */
int st_spare3; /* reserved */
long st_blksize;/* size in bytes of blocks on filesystem */
long st_blocks; /* blocks allocated for file */
long st_spare4[2]; /* reserved */
}
.fi
.LP
The items marked 'reserved' are not currently used but are reserved
for future expansion; do not use these fields for any reason.
.BR st_dev
is the number of the device on which the file resides. This number
is the same as the GS/OS device ID number.
.BR st_rdev
is not currently used, but may in the future designate a device type
code.
.LP
As short symbolic links are stored in the inode,
.IR st_blocks
may be zero.
.LP
The status information word
.I st_mode
has the following bits:
.nf
#define S_IFCHR 0020000 /* character special */
#define S_IFDIR 0040000 /* directory */
#define S_IFBLK 0060000 /* block special */
#define S_IFREG 0100000 /* regular */
#define S_IFLNK 0120000 /* symbolic link */
#define S_IFSOCK 0140000 /* socket */
#define S_IRUSR 0000400 /* read permission, owner */
#define S_IWUSR 0000200 /* write permission, owner */
#define S_IXUSR 0000100 /* execute/search permission, owner */
.fi
.LP
For a list of access modes, see <sys/stat.h>,
.BR access (2)
and
.BR chmod (2).
.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 COMPATIBILITY
BSD uses a larger set of defined fields than does GNO. The types
of the fields also, in general, differ.
.LP
The
.BR stat
man page for GNO v2.0.4 documented the macros
.BR S_IREAD ,
.BR S_IWRITE ,
and
.BR S_IEXEC .
These macros are still available in <sys/stat.h> provided that
.BR _POSIX_SOURCE
is not defined.
.SH ERRORS
.BR Stat
and
.BR lstat
will fail if:
.RS
.IP \fBENOTDIR\fR
A component of the path prefix is not a directory.
.IP \fBENOENT\fR
The named file does not exist.
.IP \fBEBADF\fR
.IR fd
does not refer to an open file.
.RE
.LP
.RS
.BR Fstat
will fail if:
.IP \fBEBADF\fR
.I fd
is not a valid open file descriptor.
.IP \fBEIO\fR
An I/O error occurred while reading from or writing to the file system.
.RE
.SH SEE ALSO
.BR chmod (2),
.BR chown (2),
.BR utimes (2)
.BR symlink (7)
.SH BUGS
GNO does not yet support hard or symbolic file links on the IIgs. Therefore,
.BR lstat
operates exactly like
.BR stat .
If there's a case where
.BR lstat
might be more appropriate at a time when links are supported, then use
.BR lstat
instead and be ready for the future.
.LP
.BR fstat
doesn't do anything clever with all the unused fields when its argument is
a pipe or terminal.
.SH STANDARDS
The
.BR stat
and
.BR fstat
function calls are close, but do not conform, to IEEE Std 1003.1-1988 (POSIX).
In particular,
.RS
.LP
\- this implementation does not make the distinction of file ownership;
.LP
\- not all the required error return codes are implemented; and
.LP
\- file access time mirrors modification time.
.RE
.SH HISTORY
An
.BR lstat
function call appeared in 4.2BSD.

103
usr.man/man2/statfs.2 Normal file
View File

@ -0,0 +1,103 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)statfs.2 8.3 (Berkeley) 2/11/94
.\"
.TH STATFS 2 "23 January 1997" GNO "System Calls"
.SH NAME
.BR statfs
\- get file system statistics
.SH SYNOPSIS
#include <sys/param.h>
.br
#include <sys/mount.h>
.sp 1
int
\fBstatfs\fR (const char *\fIpath\fR, struct statfs *\fIbuf\fR);
.sp 1
int
\fBfstatfs\fR (int \fIfd\fR, struct statfs *\fIbuf\fR);
.SH DESCRIPTION
.BR statfs
returns information about a mounted file system.
.I path
is the path name of any file within the mounted filesystem.
.I buf
is a pointer to a
.BR statfs
structure defined as follows:
.nf
typedef quad fsid_t;
struct statfs {
long f_type; /* FST type (see below) */
long f_bsize; /* fundamental file system block size */
long f_blocks; /* total data blocks in file system */
long f_bfree; /* free blocks in fs */
long f_bavail; /* free blocks avail 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 (GS/OS device number) */
long f_spare[7]; /* reserved */
}
/*
* File system types.
*/
#define MOUNT_PRODOS 0x0001 /* ProDOS or SOS */
#define MOUNT_DOS_33 0x0002 /* DOS 3.3 */
#define MOUNT_DOS_32 0x0003 /* DOS 3.1 or 3.2 */
#define MOUNT_PASCAL 0x0004 /* Apple II Pascal */
#define MOUNT_MFS 0x0005 /* Macintosh (MFS) */
#define MOUNT_HFS 0x0006 /* Macintosh (HFS) */
#define MOUNT_LISA 0x0007 /* Lisa */
#define MOUNT_CPM 0x0008 /* Apple CP/M */
#define MOUNT_MSDOS 0x000A /* MS/DOS */
#define MOUNT_HIGHS 0x000B /* High Sierra */
#define MOUNT_CD9660 0x000C /* ISO 9660 (CD-ROM) */
#define MOUNT_APLSHAR 0x000D /* AppleShare */
.fi
.LP
Fields that are undefined for a particular file system are set to -1.
.BR fstatfs
returns the same information about an open file referenced by descriptor
.IR fd .
.SH RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, -1 is returned and the global variable
.IR errno
is set to indicate the error.
.SH HISTORY
The
.BR statfs
function first appeared in 4.4BSD.

128
usr.man/man2/times.2 Normal file
View File

@ -0,0 +1,128 @@
.\" Copyright (c) 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.
.\"
.\" @(#)times.3 8.1 (Berkeley) 6/4/93
.\"
.TH TIMES 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR times
\- process times
.SH SYNOPSIS
.br
#include <sys/times.h>
.sp 1
clock_t
times (struct tms *tp);
.SH DESCRIPTION
The
.BR times
function returns the value of time in
.BR CLK_TCK 's
of a second since
0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal
Time.
.LP
It also fills in the structure pointed to by
.I tp
with time-accounting information.
.LP
The
.I tms
structure is defined as follows:
.nf
typedef struct {
clock_t tms_utime;
clock_t tms_stime;
clock_t tms_cutime;
clock_t tms_cstime;
}
.fi
.LP
The elements of this structure are defined as follows:
.RS
.IP \fItms_utime\fR
The CPU time charged for the execution of user instructions.
.IP \fItms_stime\fR
The CPU time charged for execution by the system on behalf of
the process.
.IP \fItms_cutime\fR
The sum of the
.IR tms_utime ,
and
.IR tms_cutime
of the child processes.
.IP \fItms_cstime\fR
The sum of the
.IR tms_stime ,
and
.IR tms_cstime
of the child processes.
.RE
.LP
All times are in
.BR CLK_TCK 's
of a second.
.LP
The times of a terminated child process are included in the
.I tms_cutime
and
.I tms_cstime
elements of the parent when one of the
.BR wait (2)
functions returns the process ID of the terminated child to the parent.
If an error occurs,
.BR times
returns the value
.BR (clock_t)\-1 ,
and sets errno to indicate the error.
.SH ERRORS
The
.BR times
function
may fail and set the global variable
.IR errno
for any of the errors specified for the library
routines
.BR getrusage (2)
and
.BR gettimeofday (2).
.SH SEE ALSO
.BR time (1),
.BR getrusage (2),
.BR gettimeofday (2),
.BR wait (2),
.BR clocks (7)
.SH STANDARDS
The
.BR times
function
conforms to POSIX 1003.1-88.

82
usr.man/man2/truncate.2 Normal file
View File

@ -0,0 +1,82 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)truncate.2 8.1 (Berkeley) 6/4/93
.\"
.TH TRUNCATE 2 "24 January 1997" GNO "System Calls"
.SH NAME
.BR truncate ,
.BR ftruncate
\- truncate a file to a specified length
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBtruncate\fR (const char *\fIpath\fR, off_t \fIlength\fR);
.br
int
\fBftruncate\fR (int \fIfd\fR, off_t \fIlength\fR);
.SH DESCRIPTION
.BR truncate
causes the file named by
.I path
or referenced by
.I fd
to be truncated to at most
.I length
bytes in size. If the file previously
was larger than this size, the extra data
is lost.
With
.BR ftruncate ,
the file must be open for writing.
.SH RETURN VALUES
A value of 0 is returned if the call succeeds. If the call
fails a -1 is returned, and the global variable
.IR errno
specifies the error.
.SH SEE ALSO
.BR open (2)
.SH BUGS
The GNO implementation of
.BR truncate
requires that the file must be able to be opened for writing. If
this is not possible,
.BR truncate
returns -1 and sets
.IR errno .
.LP
These calls should be generalized to allow ranges
of bytes in a file to be discarded.
.SH HISTORY
The
.BR ftruncate
function call appeared in 4.2BSD.

107
usr.man/man2/umask.2 Normal file
View File

@ -0,0 +1,107 @@
.\" 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.
.\"
.\" @(#)umask.2 8.1 (Berkeley) 6/4/93
.\"
.\" .TH UMASK 2 GNO "System Calls" "14 December 1996"
.TH UMASK 2 "14 December 1996" GNO "System Calls"
.SH NAME
.BR umask
\- set file creation mode mask
.SH SYNOPSIS
.nf
#include <sys/stat.h>
mode_t umask (mode_t \fInumask\fR);
.SH DESCRIPTION
The
.BR umask
routine sets the process's file mode creation mask to
.I numask
and returns the previous value of the mask. The 9 low-order
access permission
bits of
.I numask
are used by system calls, including
.BR open (2),
.BR mkdir (2),
and
.BR mkfifo (2),
to turn off corresponding bits
requested in file mode.
(See
.BR chmod (2)).
This clearing allows each user to restrict the default access
to his files.
.LP
The default mask value is S_IWGRP|S_IWOTH (022, write access for the
owner only).
Child processes inherit the mask of the calling process.
.LP
Because the GNO kernel does not currently implement a mask, the mask
value is maintained into child processes through the environment
variable
.BR UMASK ,
which is assumed to be a string representing an octal mask value. For
shells such as
.BR gsh (1)
which don't support a umask builtin command, the user's default mask may
be controlled by setting the
.BR UMASK
environment variable.
.SH RETURN VALUES
The previous value of the file mode mask is returned by the call.
.SH ERRORS
The
.BR umask
function will never return an error condition, however it is possible
that the
.BR setenv (3)
call used in the GNO implementation may fail. To detect this condition,
the user must set
.BR errno
to zero prior to calling
.BR umask ,
and check it's value afterward. Under most circumstances this possible
error condition may be ignored; the only side effect of
.BR setenv
failing in this case will be that the value of
.I numask
will not be maintained after an
.BR execve (2).
.SH SEE ALSO
.BR chmod (2),
.BR mknod (2),
.BR open (2)
.SH STANDARDS
The
.BR umask
function call is expected to conform to IEEE Std 1003.1-1988 (POSIX).

23
usr.man/man2/undocumented.2 Normal file
View File

@ -0,0 +1,23 @@
.\"
.\" Undocumented system calls.
.\" Devin Reade, 1997
.\"
.\" $Id: undocumented.2,v 1.1 1997/02/27 07:32:17 gdr Exp $
.\"
.TH UNDOCUMENTED 2 "16 January 1997" GNO "System Calls"
.SH NAME
.BR InstallNetDriver ,
.BR SetGNOQuitRec ,
.BR kvm_close ,
.BR kvm_getproc ,
.BR kvm_nextproc ,
.BR kvm_open ,
.BR kvm_setproc ,
.BR kvmgetproc ,
.BR kvmnextproc ,
.BR kvmsetproc ,
.BR setsystemvector
\- undocumented system calls
.SH DESCRIPTION
The system calls on this page do not have documentation at this time.
Questions regarding these routines should be forwarded to Procyon.

79
usr.man/man2/unlink.2 Normal file
View File

@ -0,0 +1,79 @@
.\" 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.
.\"
.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93
.\"
.TH UNLINK 2 "24 January 1997" GNO "System Calls"
.SH NAME
.BR unlink
\- remove directory entry
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBunlink\fR (const char *\fIpath\fR);
.SH DESCRIPTION
The
.BR unlink
function
removes the link named by
.I path
from its directory and decrements the link count of the
file which was referenced by the link.
If that decrement reduces the link count of the file
to zero,
and no process has the file open, then
all resources associated with the file are reclaimed.
If one or more process have the file open when the last link is removed,
the link is removed, but the removal of the file is delayed until
all references to it have been closed.
.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
Under currently available filesystems, there can be only a single link
to a given file.
.LP
The GNO
.BR unlink ,
unlike its Unix counterpart, cannot currently unlink an open file.
Attempting to do so will return an error.
.SH SEE ALSO
.BR close (2),
.BR link (2),
.BR rmdir (2)
.BR symlink (7)
.SH HISTORY
An
.BR unlink
function call appeared in Version 6 AT&T UNIX.

86
usr.man/man2/utimes.2 Normal file
View File

@ -0,0 +1,86 @@
.\" Copyright (c) 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.
.\"
.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93
.\"
.TH UTIMES 2 "6 January 1997" GNO "System Calls"
.SH NAME
.BR utimes
\- set file access and modification times
.SH SYNOPSIS
#include <sys/time.h>
.sp 1
int
\fButimes\fR (const char *\fIfile\fR, const struct timeval *\fItimes\fR);
.SH DESCRIPTION
The
.BR utimes
function sets the access and modification times of the named file from
the structures in the argument array
.IR times .
.LP
The first structure is the access time, and the second is the modification
time.
.LP
If the times are specified (the
.I times
argument is non-NULL)
the caller must be the owner of the file or be the super-user.
.LP
If the times are not specified (the
.I times
argument is
.BR NULL )
the caller must be the owner of the file, have permission to
write the file, or be the super-user.
.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 ERRORS
.BR Utimes
may fail and return any error that may be returned by
.BR __C2GSMALLOC (3)
or the GS/OS system calls
.BR GetFileInfoGS
or
.BR SetFileInfoGS .
.SH BUGS
The restrictions on ownership listed above are not enforced under
GNO since there is no concept of file ownership.
.SH SEE ALSO
.BR __C2GSMALLOC (3),
.BR "GS/OS Refence Manual" .
.SH HISTORY
The
.BR utimes
function call appeared in 4.2BSD.

329
usr.man/man2/wait.2 Normal file
View File

@ -0,0 +1,329 @@
.\" 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.
.\"
.\" @(#)wait.2 8.2 (Berkeley) 4/19/94
.\"
.TH WAIT 2 "19 January 1997" GNO "System Calls"
.SH NAME
.BR wait ,
.BR waitpid ,
.BR wait4 ,
.BR wait3
\- wait for process termination
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/wait.h>
.sp 1
pid_t
\fBwait\fR (union wait *\fIstatus\fR);
.sp 1
#include <sys/time.h>
.br
#include <sys/resource.h>
.sp 1
pid_t
\fBwaitpid\fR (pid_t \fIwpid\fR, union wait *\fIstatus\fR, int \fIoptions\fR);
.sp 1
pid_t
\fBwait3\fR (union wait *\fIstatus\fR, int \fIoptions\fR, struct rusage *\fIrusage\fR);
.sp 1
pid_t
\fBwait4\fR (pid_t \fIwpid\fR, union wait *\fIstatus\fR, int \fIoptions\fR, struct rusage *\fIrusage\fR);
.SH DESCRIPTION
The
.BR wait
function suspends execution of its calling process until
.I status
information is available for a terminated child process,
or a signal is received.
On return from a successful
.BR wait
call,
the
.I status
area contains termination information about the process that exited
as defined below.
.LP
The
.BR wait4
call provides a more general interface for programs
that need to wait for certain child processes,
that need resource utilization statistics accumulated by child processes,
or that require options.
.LP
The
.I wpid
parameter specifies the set of child processes for which to wait.
If
.I wpid
is -1, the call waits for any child process.
If
.I wpid
is 0,
the call waits for any child process in the process group of the caller.
If
.I wpid
is greater than zero, the call waits for the process with process id
.IR wpid .
If
.I wpid
is less than -1, the call waits for any process whose process group id
equals the absolute value of
.IR wpid .
.LP
The
.I status
parameter is defined below. The
.I options
parameter contains the bitwise OR of any of the following options.
The
.BR WNOHANG
option
is used to indicate that the call should not block if
there are no processes that wish to report status.
If the
.BR WUNTRACED
option is set,
children of the current process that are stopped
due to a
.BR SIGTTIN ,
.BR SIGTTOU ,
.BR SIGTSTP ,
or
.BR SIGSTOP
signal also have
their status reported.
.LP
If
.I rusage
is non-zero, a summary of the resources used by the terminated
process and all its
children is returned (this information is currently not available
for stopped processes).
.LP
When the
.BR WNOHANG
option is specified and no processes
wish to report status,
.BR wait4
returns a process id of 0.
.LP
The
.BR waitpid
call is identical to
.BR wait4
with an
.I rusage
value of zero.
The older
.BR wait3
call is the same as
.BR wait4
with a
.I wpid
value of -1.
.LP
The following macros may be used to test the manner of exit of the process.
One of the first three macros will evaluate to a non-zero (true) value:
.RS
.IP \fBWIFEXITED\fR(\fIstatus\fR)
True if the process terminated normally by a call to
.BR _exit (2),
.BR exit (3),
.BR rexit (3),
or a GS/OS quit call.
.IP \fBWIFSIGNALED\fR(\fIstatus\fR)
True if the process terminated due to receipt of a signal.
.IP \fBWIFSTOPPED\fR(\fIstatus\fR)
True if the process has not terminated, but has stopped and can be restarted.
This macro can be true only if the wait call specified the
.BR WUNTRACED
option
or if the child process is being traced (see
.BR ptrace (2)).
.RE
.LP
Depending on the values of those macros, the following macros
produce the remaining status information about the child process:
.RS
.IP \fBWEXITSTATUS\fR(\fIstatus\fR)
If
\fBWIFEXITED\fR(\fIstatus\fR)
is true, evaluates to the low-order 8 bits
of the argument passed to
.BR _exit (2),
.BR exit (3),
.BR rexit (3),
or a GS/OS Quit call
by the child.
.IP \fBWTERMSIG\fR(\fIstatus\fR)
If
\fBWIFSIGNALED\fR(\fIstatus\fR)
is true, evaluates to the number of the signal
that caused the termination of the process.
.IP \fBWCOREDUMP\fR(\fIstatus\fR)
If
\fBWIFSIGNALED\fR(\fIstatus\fR)
is true, evaluates as true if the termination
of the process was accompanied by the creation of a core file
containing an image of the process when the signal was received.
.I "This feature is not available under GNO."
.IP \fBWSTOPSIG\fR(\fIstatus\fR)
If
\fBWIFSTOPPED\fR(\fIstatus\fR)
is true, evaluates to the number of the signal
that caused the process to stop.
.RE
.SH NOTES
See
.BR signal (2)
for a list of termination signals.
A status of 0 indicates normal termination.
.LP
Some Unix uses of these functions expect
.IR status
to be a pointer to an
.BR int
rather than to a
.BR "union wait" .
It is safe to use a cast under such circumstances.
.LP
If a parent process terminates without
waiting for all of its child processes to terminate,
the remaining child processes
are inherited by the Kernel Null Process (pid zero).
.LP
If a signal is caught while any of the
.BR wait
calls is pending,
the call may be interrupted or restarted when the signal-catching routine
returns,
depending on the options in effect for the signal;
see
.BR intro (2),
System call restart.
.SH BUGS
Currently, only
.BR wait
is implemented in the GNO kernel. There is a minimal version of
.BR waitpid
in the libraries, but that version of
.BR waitpid
ignores its
.IR options
parameter
(making it impossible to make a non-blocking wait).
It may also give unexpected results when there is more than one
child task being waited upon.
.LP
.BR wait4
and
.BR wait3
are not implemented.
.SH RETURN VALUES
If
.BR 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
.IR errno
is set to indicate the error.
.LP
If
.BR wait4 ,
.BR wait3
or
.BR waitpid
returns due to a stopped
or terminated child process, the process ID of the child
is returned to the calling process.
If there are no children not previously awaited,
-1 is returned with
.IR errno
set to ECHILD.
Otherwise, if
.BR WNOHANG
is specified and there are
no stopped or exited children,
0 is returned.
If an error is detected or a caught signal aborts the call,
a value of -1
is returned and
.IR errno
is set to indicate the error.
.SH ERRORS
.BR Wait
will fail and return immediately if:
.RS
.IP \fBECHILD\fR
The calling process has no existing unwaited-for
child processes.
.IP \fBEFAULT\fR
The
.I status
or
.I rusage
arguments point to an illegal address.
(May not be detected before exit of a child process.)
.IP \fBEINTR\fR
The call was interrupted by a caught signal,
or the signal did not have the
.BR SA_RESTART
flag set.
.RE
.SH STANDARDS
The
.BR wait
and
.BR waitpid
functions are defined by POSIX;
.BR wait4
and
.BR wait3
are not specified by POSIX.
The
.BR WCOREDUMP
macro
and the ability to restart a pending
.BR wait
call are extensions to the POSIX interface.
.SH SEE ALSO
.BR _exit (2),
.BR execve (2),
.BR signal (2),
.BR exit (3)
.BR rexit (3)
.SH HISTORY
A
.BR wait3
function call appeared in Version 6 AT&T UNIX.

223
usr.man/man2/write.2 Normal file
View File

@ -0,0 +1,223 @@
.\" 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.
.\"
.\" @(#)write.2 8.5 (Berkeley) 4/2/94
.\"
.TH WRITE 2 "23 January 1997" GNO "System Calls"
.SH NAME
.BR write ,
.BR writev
\- write output
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/uio.h>
.br
#include <unistd.h>
.sp 1
ssize_t
\fBwrite\fR (int \fId\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);
.sp 1
ssize_t
\fBwritev\fR (int \fId\fR, const struct iovec *\fIiov\fR, int \fIiovcnt\fR);
.SH DESCRIPTION
.BR write
attempts to write
.I nbytes
of data to the object referenced by the descriptor
.I d
from the buffer pointed to by
.IR buf .
.BR writev
performs the same action, but gathers the output data
from the
.I iovcnt
buffers specified by the members of the
.I iov
array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
.LP
For
.BR writev ,
the
.I iovec
structure is defined as:
.LP
.nf
struct iovec {
void *iov_base;
size_t iov_len;
};
.fi
.LP
Each
.I iovec
entry specifies the base address and length of an area
in memory from which data should be written.
.BR writev
will always write a complete area before proceeding
to the next.
.LP
On objects capable of seeking, the
.BR write
starts at a position
given by the pointer associated with
.IR d
(see
.BR lseek (2)).
Upon return from
.BR write ,
the pointer is incremented by the number of bytes which were written.
.LP
Objects that are not capable of seeking always write from the current
position. The value of the pointer associated with such an object
is undefined.
.LP
If the real user is not the super-user, then
.BR write
clears the set-user-id bit on a file.
This prevents penetration of system security
by a user who captures
a writable set-user-id file
owned by the super-user.
.LP
When using non-blocking I/O on objects such as sockets that are subject
to flow control,
.BR write
and
.BR writev
may write fewer bytes than requested;
the return value must be noted,
and the remainder of the operation should be retried when possible.
.LP
If the file was opened with the GNO-specific flag
.BR O_TRANS ,
then newline translation will occur; any line feed (0x0a) character
present in
.IR buf
will be converted to a carridge return (0x0d) before the
.BR write
is done. See also the section on
.BR BUGS ,
below.
.SH RETURN VALUES
Upon successful completion the number of bytes which were written
is returned. Otherwise a -1 is returned and the global variable
.IR errno
is set to indicate the error.
.SH ERRORS
.BR Write
and
.BR writev
will fail and the file pointer will remain unchanged if:
.RS
.IP \fBEBADF\fR
.I D
is not a valid descriptor open for writing.
.IP \fBEPIPE\fR
An attempt is made to write to a pipe that is not open
for reading by any process.
.IP \fBEPIPE\fR
An attempt is made to write to a socket of type
.BR SOCK_STREAM
that is not connected to a peer socket.
.IP \fBEFBIG\fR
An attempt was made to write a file that exceeds the process's
file size limit or the maximum file size.
.IP \fBEFAULT\fR
Part of
.I iov
or data to be written to the file
points outside the process's allocated address space.
.IP \fBEINVAL\fR
The pointer associated with
.I d
was negative.
.IP \fBENOSPC\fR
There is no free space remaining on the file system
containing the file.
.IP \fBEDQUOT\fR
The user's quota of disk blocks on the file system
containing the file has been exhausted.
.IP \fBEIO\fR
An I/O error occurred while reading from or writing to the file system.
.IP \fBEAGAIN\fR
The file was marked for non-blocking I/O,
and no data could be written immediately.
.RE
.LP
In addition,
.BR writev
may return one of the following errors:
.RS
.IP \fBEINVAL\fR
.I Iovcnt
was less than or equal to 0, or greater than
.BR UIO_MAXIOV .
.IP \fBEINVAL\fR
One of the
.I iov_len
values in the
.I iov
array was negative.
.IP \fBEINVAL\fR
The sum of the
.I iov_len
values in the
.I iov
array overflowed a 32-bit integer.
.RE
.SH BUGS
If the GNO-specific flag
.BR O_TRANS
was specified when the descriptor
.IR d
was opened, then
.IR buf
may be modified by this call; the newline translation is done in-place.
.SH SEE ALSO
.BR fcntl (2),
.BR lseek (2),
.BR open (2),
.BR pipe (2),
.BR select (2)
.SH STANDARDS
.BR Write
is expected to conform to IEEE Std 1003.1-1988 (POSIX).
.SH HISTORY
The
.BR writev
function call
appeared in 4.2BSD.
A
.BR write
function call
appeared in
Version 6 AT&T UNIX.

340
usr.man/man3/GSString.3 Normal file
View File

@ -0,0 +1,340 @@
.\" Man page by Devin Reade
.\"
.\" $Id: GSString.3,v 1.1 1997/02/27 07:32:20 gdr Exp $
.\"
.TH GSSTRING 3 "15 December 1996" GNO "Library Routines"
.SH NAME
.BR GIinit ,
.BR GIchange ,
.BR GIfree ,
.BR GOinit ,
.BR GOchange ,
.BR GOfree ,
.BR __C2GS ,
.BR __C2GSMALLOC ,
.BR __GS2C ,
.BR __GS2CMALLOC
\- GSString and ResultBuf handling routines
.SH SYNOPSIS
#include <types.h>
.br
#include <gno/gno.h>
.sp 1
GSStringPtr GIinit (word \fIlen\fR, const char *\fIstr\fR);
.br
GSStringPtr GIchange (GSStringPtr \fIorg\fR, word \fIlen\fR, const char *\fIstr\fR);
.br
void GIfree (GSStringPtr \fIstr\fR);
.sp 1
ResultBufPtr GOinit (word \fIlen\fR, const char *\fIstr\fR);
.br
ResultBufPtr GOchange (ResultBufPtr \fIorg\fR, word \fIlen\fR, const char *\fIstr\fR);
.br
void GOfree (ResultBufPtr \fIstr\fR);
.sp 1
GSStringPtr __C2GS (char *\fIstr\fR, GSStringPtr \fIgp\fR);
.br
GSStringPtr __C2GSMALLOC (const char *\fIstr\fR);
.br
char * __GS2C (char *\fIstr\fR, GSStringPtr \fIgp\fR);
.br
char * __GS2CMALLOC (GSStringPtr \fIgp\fR);
.SH DESCRIPTION
There are some occasionally undesired restrictions in the way
GS/OS input and output
strings are handled by the Orca/C headers. Fixed length strings have one
advantage (they are slightly easier to handle than dynamic ones), and
several disadvantages:
.RS
.LP
If they're too small, they're too small. If you think that
nobody will construct a pathname more than 255 characters long, I heartily
recommend
.IR "Can't Happen or /* NOTREACHED */ or Real Programs Dump Core" ,
by Ian Darwin and Geoff Collyer, USENIX Association Winter Conference,
Dallas 1985 Proceedings.
.LP
They take up memory regardless of whether or not it's used.
.LP
They're a hassle when you want to write reentrant code. With stack space
at a premium on the IIgs, an automatic GSString255 or ResultBuf255 is out
of the question. A static or global one might get you into sync problems.
.RE
.LP
These routines solve the above problems in a simple way. There are now six
new struct pointers declared,
.BR GSStringPtr ,
.BR GSStringHndl ,
.BR GSStringHndlPtr ,
.BR ResultBufPtr ,
.BR ResultBufHndl ,
and
.BR ResultBufHndlPtr .
These are dynamic counterparts to the
.BR GSString255Ptr
and similar pointers defined by default in the Orca/C <types.h> header,
and may
be used in place of those default Orca/C pointers in the various tool
box calls (although a cast may be required to quiesce the compiler).
The key difference is that the application programmer is able to specify
the size of the strings, rather than going with the default 32 or 255 bytes.
.LP
Note that there is no
.BR GSString
or
.BR ResultBuf
typedef, as the structures to which these pointers refer should not
be used directly; unless properly allocated, they have a text space of
only one byte.
.LP
.BR GIinit
.RS
.BR GSString s
must be allocated and initialized using the
.BR GIinit
(or
.BR GIchange )
routines.
On success, the
.BR length
field of the structure pointed to by
.BR GIinit
will be set to
.IR len ,
and the
.BR text
field will be
.IR len +1
bytes long.
The extra (last) byte in this field is provided so that it can be
used for a NULL terminating byte.
.LP
If
.IR str
is non-NULL, it's contents (which is assumed to be a NULL-terminated C
string) will be copied into the
.BR text
field, up to a maximum of
.IR len
bytes, and will be NULL terminated.
If
.BR str
is NULL, a NULL-terminating byte will be placed in both the first and
final byte positions in the
.BR text
field.
On failure,
.BR GIinit
will return the NULL pointer.
.RE
.LP
.BR GIchange
.RS
The
.BR GIchange
routine is used to change the size of a GSString. It is similar to
.BR GIinit
.RB ( GIinit
is implemented in terms of
.BR GIchange ),
except that it takes an additional parameter,
.IR org ,
which is a
.BR GSStringPtr
holding the result of a previous call to either
.BR GIinit
or
.BR GIchange .
.LP
If
.IR org
is NULL,
.BR GIchange
behaves exactly like
.BR GIinit .
If
.IR org
is non-NULL, then the GSString pointed to by
.IR org
will be copied into the returned result, and the memory pointed to by
.IR org
will no longer be usable.
Note that if
.IR len
is greater than the previous length of
.IR org
and
.IR str
is NULL, the latter part of the
.BR text
field will be uninitialized, except that there will be a terminating NULL
byte at the end of the
.BR text
field (as well as the original NULL-terminating byte at the end of
the old
.BR text
field).
.LP
On success,
.BR GIchange
returns the new GSString. On failure it returns NULL and sets
.BR errno .
.LP
Note that if this call succeeds, the region pointed to by
.IR org
subsequently may not be legally referenced. If the call fails,
.IR org
is unchanged.
.RE
.LP
.BR GIfree
.RS
.BR GIfree
is used to deallocate memory allocated with either
.BR GIinit
or
.BR GIchange .
It is currently implemented as a macro.
.RE
.LP
.BR GOinit
.br
.BR GOchange
.RS
The behavior of
.BR GOinit
and
.BR GOchange
are similar to the routines
.BR GIinit
and
.BR GIchange ,
respectively, except that if
.IR str
is NULL, the
.BR bufString->length
and
.BR bufString->text
fields of the result will be unmodified, unless:
.RS
.LP
.IR org
is also NULL, in which case these fields are set to be the empty
string; or
.LP
.IR len
is less than the length of the GSString
.IR org ,
in which case the
.BR bufString->length
is set to
.IR len .
.LP
.RE
A terminating NULL byte will always be placed in the
last character of
.BR bufString->text .
.RE
.LP
.BR GOfree
.RS
.BR GOfree
is used to deallocate memory allocated with either
.BR GOinit
or
.BR GOchange .
It is currently implemented as a macro.
.RE
.LP
.BR __C2GSMALLOC
.RS
.BR __C2GSMALLOC
takes a C-style string
.I str
and returns a GSStringPtr pointing to a Class 1 GS/OS string containing
a copy of
.IR str .
The returned GS/OS string will have an NULL-terminating extra byte in the
.BR text
field.
Space allocated by this routine should be released with
.BR GIfree
when it is no longer required.
On failure the NULL pointer is returned.
.RE
.LP
.BR __C2GS
.RS
.BR __C2GS
converts a C string to a Class 1 GS/OS string, where
.IR gp
points to space for the result which is already allocated.
The required space for this routine is:
.nf
sizeof(word) + strlen(\fIstr\fR) + 1
.fi
Failure to provide sufficient space may result in memory corruption;
.IR "this routine should be used with caution" .
If the C string is too long to fit in a GS/OS string,
.BR __C2GS
returns NULL and sets
.BR errno .
.RE
.LP
.BR __GS2CMALLOC
.RS
.BR __GS2CMALLOC
is similar to
.BR __C2GSMALLOC ,
but the direction of conversion is reversed.
The result of
.BR __GS2CMALLOC
will be a pointer to memory allocated by
.BR malloc (3)
and should be released with
.BR free (3)
when it is no longer required.
.RE
.LP
.BR __GS2C
.RS
.BR __GS2C
is similar to
.BR __C2GS ,
but the direction of conversion is reversed.
.BR __GS2C
expects the memory region pointed to by
.IR str
to be sufficiently large to hold the result (this should be at least
\fIgp\fB->length\fR + 1); if this is not so, then memory corruption may
occur.
.BR __GS2C
always returns
.IR str .
.SH CAVEATS
Although these routines operate in similar ways, it is an error to mix
these routines. For example, the
.BR bufString
field of a ResultBuf cannot be resized using
.BR GIchange ;
instead
.BR GOchange
must be used.
.SH AUTHOR
The GI and GO routines are based on code by
Soenke Behrens <s_behrens@emulex.com>.
.LP
The remaining routines
were reimplemented from spec by Devin Reade <gdr@myrias.com>.
.SH HISTORY
The GI and GO routines first appeared in the
.IR "GSString Library"
under slightly different names.
.LP
.BR __C2GSMALLOC ,
.BR __GS2CMALLOC ,
and
.BR __GS2C
first appeared in GNO v1.0.
.SH "SEE ALSO"
.I "GS/OS Reference Manual"

32
usr.man/man3/Intro.3 Normal file
View File

@ -0,0 +1,32 @@
.\"
.\" Devin Reade, January 1997
.\"
.\" $Id: Intro.3,v 1.1 1997/02/27 07:32:20 gdr Exp $
.\"
.TH INTRO 3 "12 January 1997" GNO "Library Routines"
.SH NAME
Intro \- Introduction Library Functions
.SH DESCRIPTION
This chapter describes library functions. These are routines which do
not directly access the GNO kernel.
.LP
The
.BR SYNOPSIS
section of each manual page gives the prototype for the function(s)
described, along with a listing of the header files which provide
the prototypes. The sequence of header file inclusion may be important,
so they should be included in the sequence given.
.LP
The
.BR DESCRIPTION
section gives the detailed description of the function.
Note that since functions in this section are not system calls, you
cannot in general assume that the global integer variable
.BR errno
will be relevent to any error condition. The only way to detect an
error condition is to use the mechanism, if any, described in the
relevent manual page.
.SH "SEE ALSO"
There are many references for programming under GNO. See the
Frequently Asked Questions (FAQ) list for the USENET newsgroup
comp.sys.apple.gno for a discussion on this topic.

66
usr.man/man3/basename.3 Normal file
View File

@ -0,0 +1,66 @@
.\"
.\" Routines and man page by Devin Reade
.\"
.\" $Id: basename.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH BASENAME 3 "26 November 1995" GNO "Library Routines"
.SH NAME
.BR basename ,
.BR dirname
\- get components of a pathname
.SH SYNOPSIS
#include <unistd.h>
.sp 1
char *\fBbasename\fR (const char *\fIpath\fR);
.br
char *\fBdirname\fR (const char *\fIpath\fR);
.SH DESCRIPTION
.B basename
returns a pointer to the file component of
.IR path .
If
.I path
ends with a directory separator, then
.B basename
returns an empty string.
.LP
.B dirname
returns a pointer to an internal buffer containing the directory
component of
.IR path ,
without a trailing directory separator.
If
.I path
ends with a directory separator, then that character is the only part
of
.I path
not included in the resultant string.
If
.I path
is NULL, an empty string is returned.
.LP
Unlike
.BR ExpandPathGS (2),
.BR dirname
does not expand any GS/OS prefixes that may be present in
.IR path .
.LP
Under GS/OS, permissable directory separators are
.B :
and
.BR / ,
with the former taking precedence.
.SH COMPATIBILITY
.BR basename
is thread-safe;
.BR dirname
is not.
.SH BUGS
If
.IR path
is longer than PATH_MAX characters,
.BR dirname
will only consider the first PATH_MAX-1 characters.
.SH AUTHOR
Devin Reade <gdr@myrias.com>

75
usr.man/man3/bcopy.3 Normal file
View File

@ -0,0 +1,75 @@
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\"
.\" 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.
.\"
.\" @(#)bcopy.3 8.1 (Berkeley) 6/4/93
.\"
.TH BCOPY 3 "26 January 1997" GNO "Library Routines"
.SH NAME
.BR bcopy
\- copy byte string
.SH SYNOPSIS
#include <string.h>
.sp 1
void
\fBbcopy\fR (const void *\fIsrc\fR, void *\fIdst\fR, size_t \fIlen\fR);
.SH DESCRIPTION
The
.BR bcopy
function
copies
.I len
bytes from string
.I src
to string
.IR dst .
If
.I len
is zero, no bytes are copied.
.LP
The two strings may overlap. This is different than the implementation of
.BR bcopy
in versions of GNO prior to v2.0.6;
.BR bcopy
is no longer implemented in terms of
.BR memcpy .
.SH SEE ALSO
.BR memccpy (3),
.BR memcpy (3),
.BR memmove (3),
.BR strcpy (3),
.BR strncpy (3)
.SH HISTORY
A
.BR bcopy
function appeared in 4.2BSD.

45
usr.man/man3/buildCmd.3 Normal file
View File

@ -0,0 +1,45 @@
.\" This man page was written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade.
.\"
.\" $Id: buildCmd.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH BUILDCMD 3 "30 January 1997" GNO "Library Routines"
.SH NAME
buildCmd - build a command string from an argument vector
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
char *\fBbuildCmd\fR (char *const *\fIargv\fR);
.SH DESCRIPTION
.BR buildCmd
constructs a single string from the NULL-terminated array of arguments
.IR argv .
The string will be allocated via
.BR malloc (3),
and will consist of all of the elements of
.IR argv ,
delimited by single spaces.
.LP
If
.IR argv [0]
is NULL, a zero-length string will be constructed.
Any GS/OS prefix (numerical or otherwise) on
.IR argv [0]
will be stripped.
.SH RETURN VALUE
On success,
.BR buildCmd
returns the constructed string. On failure it returns NULL.
.SH HISTORY
This routine was originally called
.BR build_cmd
and was part of the
.BR lenviron
library written by Devin Reade for GNO v2.0.3 in April 1994.
It was incorporated into the GNO
.BR libc
as of v2.0.6.
.SH SEE ALSO
.BR buildEnv (3),
.BR buildPath (3),
.BR environ (7).

36
usr.man/man3/buildEnv.3 Normal file
View File

@ -0,0 +1,36 @@
.\" This man page was written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade.
.\"
.\" $Id: buildEnv.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH BUILDENV 3 "30 January 1997" GNO "Library Routines"
.SH NAME
buildEnv - add a vector of strings to the process environment
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int \fBbuildEnv\fR (char * const *\fIenvp\fR);
.SH DESCRIPTION
.BR buildEnv
takes takes a NULL-terminated array of character string pointers,
where each string is of the format
.I NAME=VALUE
and adds the strings to the process environment via
.BR putenv (3).
.SH RETURN VALUE
.B buildEnv
returns zero on success. On failure, it returns -1 and sets
.IR errno .
.SH HISTORY
This routine was originally called
.BR build_env
and was part of the
.BR lenviron
library written by Devin Reade for GNO v2.0.3 in April 1994.
It was incorporated into the GNO
.BR libc
as of v2.0.6.
.SH SEE ALSO
.BR buildCmd (3),
.BR buildPath (3),
.BR environ (7).

65
usr.man/man3/buildPath.3 Normal file
View File

@ -0,0 +1,65 @@
.\" This man page was written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade.
.\"
.\" $Id: buildPath.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH BUILDPATH 3 "30 January 1997" GNO "Library Routines"
.SH NAME
buildPath - search PATH and return the full path name of an executable file
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
char *\fBbuildPath\fR (const char *\fIfile\fR);
.SH DESCRIPTION
.BR buildPath
searches the directories listed in the
.BR PATH
environment variable for
.IR file .
.LP
If
.IR file
resides within
.BR PATH ,
then
.BR buildPath
constructs a string with
.BR malloc (3)
which contains the full pathname of the file. If
.IR file
itself specifies a fully qualified pathname, then the constructed
string will be a copy of
.IR file ,
and no test for existence will be done.
.LP
If PATH is not set or is the empty string, then
.BR buildPath
will default to searching
.BR bin
then
.BR /usr/bin .
.SH RETURN VALUES
On success, the constructed string is returned. On error, NULL is
returned and
.BR errno
is set.
.SH CAVEATS
The current version of
.BR gsh
parse the PATH variable backwards, so for compatibility
.BR buildPath
will currently also search PATH backwards.
.SH HISTORY
This routine was originally called
.BR build_path
and was part of the
.BR lenviron
library written by Devin Reade for GNO v2.0.3 in April 1994.
It was incorporated into the GNO
.BR libc
as of v2.0.6.
.SH SEE ALSO
.BR buildCmd (3),
.BR buildEnv (3),
.BR isRootPath (3),
.BR environ (7).

69
usr.man/man3/bzero.3 Normal file
View File

@ -0,0 +1,69 @@
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\"
.\" 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.
.\"
.\" @(#)bzero.3 8.1 (Berkeley) 6/4/93
.\"
.TH BZERO 3 "26 January 1997" GNO "Library Routines"
.SH NAME
.BR bzero
\- write zeroes to a byte string
.SH SYNOPSIS
#include <string.h>
.sp 1
void
\fBbzero\fR (void *\fIb\fR, size_t \fIlen\fR);
.SH DESCRIPTION
The
.BR bzero
function
writes
.I len
zero bytes to the string
.IR b .
If
.I len
is zero,
.BR bzero
does nothing.
It is functionally equivalent to and implemented as
\fBmemset\fR(\fIb\fR,0,\fIlen\fR), and is included solely for
BSD compatibility.
.SH SEE ALSO
.BR memset (3),
.BR swab (3)
.SH HISTORY
A
.BR bzero
function
appeared in 4.3BSD.

162
usr.man/man3/crypt.3 Normal file
View File

@ -0,0 +1,162 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)crypt.3 8.2 (Berkeley) 12/11/93
.\"
.TH CRYPT 3 "28 January 1997" GNO "Library Routines"
.SH NAME
.BR crypt ,
.BR setkey ,
.BR encrypt ,
\- simple encryption
.SH SYNOPSIS
#include <unistd.h>
.sp 1
char
*\fBcrypt\fR (const char *\fIkey\fR, const char *\fIsalt\fR);
.br
int
\fBsetkey\fR (char *\fIkey\fR);
.br
int
\fBencrypt\fR (char *\fIblock\fR, int \fIflag\fR);
.SH DESCRIPTION
The
.BR crypt
function
performs password encryption.
It is derived from an algorithm given in
.I "Computer Networks"
by Andy Tanenbaum.
.LP
The first argument to
.BR crypt
.RI ( key )
is a
.BR NULL -terminated
string (normally a password typed by a user).
The second,
.IR salt ,
is a two-character array 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
.BR /etc/passwd
password entry in the case of validating a password.
.LP
The
functions,
.BR encrypt
and
.BR setkey
allow limited access to the encryption
algorithm itself.
The
.IR key
argument to
.BR setkey
is a 64 character array of
binary values (numeric 0 or 1).
A 56-bit key is derived from this array by dividing the array
into groups of 8 and ignoring the last bit in each group.
.LP
The
.BR encrypt
argument
.I block
is also a 64 character array of
binary values.
If the value of
.I flag
is 0,
the argument
.I block
is encrypted, otherwise it
is decrypted.
The encryption or decryption is returned in the original
array
.I block
after using the
key specified
by
.BR setkey
to process it.
.LP
The function
.BR crypt
returns a pointer to the encrypted value (which is formatted as
printable ASCII characters) on success and NULL on failure.
The functions
.BR setkey
and
.BR encrypt
return 0 on success and 1 on failure.
.LP
Use of these routines requires linking with the
.BR libcrypt
library.
.SH SEE ALSO
.BR login (1),
.BR passwd (1),
.BR getpass (3),
.BR passwd (5)
.sp
.RS
.I "Mathematical Cryptology for Computer Scientists and Mathematicians"
by
Wayne Patterson.
1987.
Volume ISBN 0-8476-7438-X.
.RE
.sp 1
.RS
.I "Password Security: A Case History"
by
R. Morris,
Ken Thompson.
.IR "Communications of the ACM" ,
vol. 22, pp. 594-597. November 1979.
.RE
.sp 1
.RS
.I "DES will be Totally Insecure within Ten Years"
by
M.E. Hellman.
.IR "IEEE Spectrum" ,
vol. 16, pp. 32-39. July 1979.
.RE
.SH BUGS
The
.BR crypt
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.BR crypt
will modify the same object.

228
usr.man/man3/directory.3 Normal file
View File

@ -0,0 +1,228 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)directory.3 8.1 (Berkeley) 6/4/93
.\"
.TH DIRECTORY 3 "29 January 1997" GNO "Library Routines"
.SH NAME
.BR opendir ,
.BR readdir ,
.BR telldir ,
.BR seekdir ,
.BR rewinddir ,
.BR closedir ,
.BR dirfd
\- directory operations
.SH SYNOPSIS
.nf
#include <sys/types.h>
#include <dirent.h>
DIR *\fBopendir\fR (const char *\fIfilename\fR);
struct \fBdirent\fR *readdir (DIR *\fIdirp\fR);
long \fBtelldir\fR (const DIR *\fIdirp\fR);
void \fBseekdir\fR (DIR *\fIdirp\fR, long \fIloc\fR);
void \fBrewinddir\fR (DIR *\fIdirp\fR);
int \fBclosedir\fR (DIR *\fIdirp\fR);
int \fBdirfd\fR (DIR *\fIdirp\fR);
.fi
.SH DESCRIPTION
The
.BR opendir
function
opens the directory named by
.IR filename ,
associates a
.IR "directory stream"
with it
and
returns a pointer to be used to identify the
.IR "directory stream"
in subsequent operations. The pointer
.BR NULL
is returned if
.I filename
cannot be accessed, or if it cannot
.BR malloc (3)
enough memory to hold the whole thing.
.LP
The
.BR readdir
function
returns a pointer to the next directory entry. It returns
.BR NULL
upon reaching the end of the directory or detecting an invalid
.BR seekdir
operation.
The GNO implementation will not return entries for either the current
directory
.RB ( . )
or the parent directory
.RB ( .. ).
Directory entries are defined by the following structure in <sys/dirent.h>:
.nf
struct dirent {
unsigned long d_fileno; /* file number of entry */
unsigned short d_reclen; /* length of this record */
unsigned char d_type; /* file type (non-IIgs) */
unsigned char d_namlen; /* length of string in d_name */
char d_name[256]; /* name must be no longer than this */
}
.fi
The value of
.BR d_fileno
is, on most architectures, the inode of the current file. Since inodes
are not used on any current GS/OS FSTs, this number corresponds to the
offset of this file in the current directory.
.BR d_reclen
is the length of the entire struct dirent.
The
.BR d_type
member is currently set to
.BR DT_DIR
for directories,
.BR DT_REG
otherwise.
.BR d_namlen
is the length of the file name contained in
.BR d_name .
.LP
Subsequent calls to
.BR readdir
will overwrite previous results in the struct dirent; if the results
must be saved then they should be
.BR memcpy \'d
to a user-defined buffer.
.LP
The
.BR telldir
function
returns the current location associated with the named
.IR "directory stream" .
The result of a
.BR telldir
on a stream which has just been opened is undefined.
.LP
The
.BR seekdir
function
sets the position of the next
.BR readdir
operation on the
.IR "directory stream" .
The new position reverts to the one associated with the
.IR "directory stream"
when the
.BR telldir
operation was performed. Values returned by
.BR telldir
are good only for the lifetime of the
.BR DIR
pointer,
.RI ( dirp )
from which they are derived.
If the directory is closed and then reopened, the
.BR telldir
value may be invalidated due to undetected directory compaction.
.LP
The
.BR rewinddir
function
resets the position of the named
.IR "directory stream"
to the beginning of the directory.
.LP
The
.BR closedir
function
closes the named
.IR "directory stream"
and frees the structure associated with the
.I dirp
pointer,
returning 0 on success.
On failure, \-1 is returned and the global variable
.IR errno
is set to indicate the error.
.LP
The
.BR dirfd
function
returns the integer file descriptor associated with the named
.IR "directory stream" ,
see
.BR open (2).
.SH EXAMPLE
Sample code which searches a directory for entry ``name'' in a
case-sensitive manner is:
.nf
len = strlen(name);
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL)
if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
(void)closedir(dirp);
return FOUND;
}
(void)closedir(dirp);
return NOT_FOUND;
.fi
.SH BUGS
The GNO implementation of
.BR seekdir
and
.BR rewinddir
rely on the GS/OS call
.BR GetDirEntryGS .
It is thus possible for these routines to fail. If they do, the error
will not be detected until a subsequent
.BR readdir
is performed.
.SH SEE ALSO
.BR open (2),
.BR close (2),
.BR read (2),
.BR lseek (2),
.BR dir (5)
.SH HISTORY
The
.BR opendir ,
.BR readdir ,
.BR telldir ,
.BR seekdir ,
.BR rewinddir ,
.BR closedir ,
and
.BR dirfd
functions appeared in
BSD 4.2.

148
usr.man/man3/err.3 Normal file
View File

@ -0,0 +1,148 @@
.\" Copyright (c) 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.
.\"
.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93
.\" $Id: err.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH ERR 3 "April 13, 1995" GNO "Library Routines"
.SH NAME
.BR err ,
.BR verr ,
.BR errx ,
.BR verrx ,
.BR warn ,
.BR vwarn ,
.BR warnx ,
.BR vwarnx ,
.BR err_set_file ,
.BR err_set_exit
\- formatted error messages
.SH SYNOPSIS
.nf
#include <err.h>
void err (int \fIeval\fR, const char *\fIfmt\fR, ...);
void verr (int \fIeval\fR, const char *\fIfmt\fR, va_list \fIargs\fR);
void errx (int \fIeval\fR, const char *\fIfmt\fR, ...);
void verrx (int \fIeval\fR, const char *\fIfmt\fR, va_list \fIargs\fR);
void warn (const char *\fIfmt\fR, ...);
void vwarn (const char *\fIfmt\fR, va_list \fIargs\fR);
void warnx (const char *\fIfmt\fR, ...);
void vwarnx (const char *\fIfmt\fR, va_list \fIargs\fR);
void err_set_file (void *\fIfp\fR);
void err_set_exit (void (*\fIexitf\fR)(int));
.fi
.SH DESCRIPTION
The
.BR err
and
.BR warn
family of functions display a formatted error message on the standard
error output, or on another file specified using the
.BR err_set_file
function.
In all cases, the last component of the program name, a colon character,
and a space are output.
If the
.IR fmt
argument is not NULL, the formatted error message, a colon character,
and a space are output.
In the case of the
.BR err ,
.BR verr ,
.BR warn ,
and
.BR vwarn
functions, the error message string affiliated with the current value of
the global variable
.IR errno
is output.
In all cases, the output is followed by a newline character.
.LP
The
.BR err ,
.BR verr ,
.BR errx ,
and
.BR verrx
functions do not return, but exit with the value of the argument
.RI ( eval )
The
.BR err_set_exit
function can be used to specify a function which is called before
.BR exit (3)
to perform any necessary cleanup; passing a null function pointer for
.IR exitf
resets the hook to do nothing.
.SH EXAMPLES
Display the current errno information string and exit:
.RS
.nf
if ((p = malloc(size)) == NULL)
err(1, NULL);
if ((fd = open(file_name, O_RDONLY, 0)) == -1)
err(1, "%s", file_name);
.fi
.RE
.LP
Display an error message and exit:
.RS
.nf
if (tm.tm_hour < START_TIME)
errx(1, "too early, wait until %s", start_time_string);
.fi
.RE
.LP
Warn of an error:
.RS
.nf
if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
warnx("%s: %s: trying the block device",
raw_device, strerror(errno));
if ((fd = open(block_device, O_RDONLY, 0)) == -1)
err(1, "%s", block_device);
.fi
.RE
.SH "SEE ALSO"
.BR exit (3),
.BR strerror (3)
.SH HISTORY
The
.BR err
and
.BR warn
functions first appeared in 4.4BSD.

81
usr.man/man3/exec.3 Normal file
View File

@ -0,0 +1,81 @@
.\"
.\" $Id: exec.3,v 1.1 1997/02/27 07:32:22 gdr Exp $
.\"
.TH EXEC 3 "19 January 1997" GNO "Library Routines"
.SH NAME
.BR exec
\- load an executable file and launch as a new process
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBexec\fR(const char *\fIpathname\fR, const char *\fIcmdline\fR);
.SH DESCRIPTION
This call is provided only for backward compatibility and should be
avoided. New programs should use the
.BR execve (2)
family of calls, the
.BR system (3)
routine, or the
.BR EXECUTE
shell call.
.LP
.BR exec
is an alternative method for launching a new process under GNO.
It is a combination of the
.BR fork (2)
and
.BR _execve (2)
system calls, and is in fact written in terms of them. The difference
between
.BR exec
and
.BR _execve
is that
.BR exec
returns in all cases; it is a simplified interface for those who don't
need to affect process information before a new executable begins
(such as process group IDs or I/O redirection information).
.LP
The (somewhat simplified) algorithm for
.BR exec
is as follows:
.RS
.nf
void exec2() {
return _execve();
}
int exec() {
return fork(exec2);
}
.fi
.RE
.SH RETURN VALUE
.BR exec
returns the process ID of the child, or -1 (and setting
.BR errno )
if an error occurs in either the
.BR fork
or
.BR _execve
call.
.SH BUGS
See the BUGS section in the
.BR execve (2)
man page.
.LP
If an error occurs in the
.BR _execve
phase of this call, it can only be detected with the
.BR wait (2)
system call; it will get the return code of the process, which will be -1
if the
.BR _execve
fails.
.SH SEE ALSO
.BR execve (2),
.BR fork (2),
.BR wait (2),
.BR execl (3),
.BR system (3).

187
usr.man/man3/execl.3 Normal file
View File

@ -0,0 +1,187 @@
.\" Copyright (c) 1991 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.
.\"
.\" from: @(#)exec.3 6.4 (Berkeley) 4/19/91
.\" exec.3,v 1.2 1993/07/30 08:35:49 mycroft Exp
.\"
.\" This man page has been modified to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade. glyn@cs.ualberta.ca
.\"
.TH EXECL 3 "19 January 1997" GNO "Library Routines"
.SH NAME
.BR execl ,
.BR execlp ,
.BR execv ,
.BR execvp
\- execute a file
.SH SYNOPSIS
#include <unistd.h>
.sp 1
extern char **environ;
.sp 1
int
\fBexecl\fR(const char *\fIpath\fR, const char *\fIarg\fR, ...);
.br
int
\fBexecle\fR(const char *\fIpath\fR, const char *\farg\fR, ...);
.br
int
\fBexeclp\fR(const char *\fIfile\fR, const char *\fIarg\fR, ...);
.br
int
\fBexecv\fR(const char *\fIpath\fR, char * const *\fIargv\fR);
.br
int
\fBexecvp\fR(const char *\fIfile\fR, char * const *\fIargv\fR);
.SH DESCRIPTION
The
.BR exec
family of functions replaces the current process image with a
new process image.
The functions described in this manual page are front-ends for the function
\fIexecve\fR(2). (See the manual page for \fIexecve\fR
for detailed information about the replacement of the current process.)
.LP
The initial argument for these functions is the pathname of a file which
is to be executed.
.LP
The
.I arg
and subsequent ellipses in the
.IR execl ,
.IR execle ,
and
.I execlp
functions can be thought of as
.IR arg0 ,
.IR arg1 ,
.IR "..." ,
.IR argn .
Together they describe a list of one or more pointers to NULL-terminated
strings that represent the argument list available to the executed program.
The first argument, by convention, should point to the file name associated
with the file being executed.
The list of arguments
.I must
be terminated by a NULL pointer.
.LP
The
.BR execle
function expects a final argument,
.BR envp ,
of type 'char * const *' to follow
the trailing NULL pointer. This is an array of environment strings,
similar to that used by
.BR execve (2).
This array
.IR must
be NULL-terminated.
.LP
The
.I execv
and
.I execvp
functions provide an array of pointers to NULL-terminated strings that
represent the argument list available to the new program.
The first argument, by convention, should point to the file name associated
with the file begin executed.
The array of pointers
.I must
be terminated by a NULL pointer.
.LP
Some of these functions have special semantics.
.LP
The functions
.I execlp
and
.I execvp
will duplicate the actions of the shell in searching for an executable file
if the specified file name does not contain a slash (/) character or a
colon (:).
The search path is the path specified in the environment by
.B PATH
variable.
If this variable isn't specified, the default path
.BR "/bin /usr/bin"
(or
.BR "/usr/bin /bin"
for
.BR gsh (1))
is used.
.SH RETURN VALUES
If any of the
.I exec
functions returns, an error will have occurred.
The return value is \fBSYSERR\fR (\-1), and the global variable
.B errno
will be set to indicate the error.
.SH ERRORS
These routines may fail and set
.B errno
for any of the errors specified for the library functions
.IR execve (2),
.IR _execve (2),
and
.IR malloc (3).
.SH GNO IMPLEMENTATION
When parsing the
.B PATH
environment variable,
.I execvp
and
.I execlp
assume that if there is no colon (:) within
.B PATH
then the pathname delimiter is a slash (/). This is to facilitate use
of GS/OS pathname delimiters.
.LP
The current version of the gsh shell searches
.B PATH
from back to front. In most other shells, it is done front to back. In
order to provide consistency with gsh,
.B PATH
is currently scanned back to front. With this backwards scanning, the
default
.B PATH
used is
.BR "/usr/bin /bin" .
If gsh gets fixed, the
scan order will be quickly changed.
.SH AUTHOR
Implemented from the BSD specification by Devin Reade.
.SH SEE ALSO
.BR execve (2),
.BR fork (2),
.BR exec (3C).
.SH HISTORY
The GNO implementation of these routines first appeared in the
.BR lenviron
library. They became part of the GNO distribution as of v2.0.6

116
usr.man/man3/exit.3 Normal file
View File

@ -0,0 +1,116 @@
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" 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.
.\"
.\" @(#)exit.3 8.1 (Berkeley) 6/4/93
.\"
.TH EXIT 3 "22 January 1997" GNO "Library Routines"
.SH NAME
.BR exit ,
.BR _exit ,
.BR rexit
\- perform normal program termination
.SH SYNOPSIS
#include <stdlib.h>
.sp 1
void
\fBexit\fR (int \fIstatus\fR);
.br
void
\fBrexit\fR (int \fIstatus\fR);
.sp 1
#include <unistd.h>
.sp 1
void
\fB_exit\fR (int \fIstatus\fR);
.SH DESCRIPTION
.BR exit
terminates a process.
.LP
Before termination
.BR exit
performs the following functions in the order listed:
.RS
.sp 1
Call the functions registered with the
.BR atexit (3)
function, in the reverse order of their registration.
.sp 1
Flush all open output streams.
.sp 1
Close all open streams.
.sp 1
Unlink all files created with the
.BR tmpfile (3)
function.
.RE
.LP
.BR rexit
is identical to
.BR exit ,
except that the process image will be flagged to GS/OS as restartable.
.LP
.BR _exit
is similar to
.BR exit ,
except that no clean up is done except for the flushing and closing of
any open streams.
.BR _exit
is the proper function to call when a child process exits while still
executing in the address space of its parent process, such as after
a failed
.BR execve (2)
call.
.LP
Passing arbitrary values back to the environment as
.BR status
is considered bad style. Instead, use the values as described in
.BR sysexits (3).
.SH RETURN VALUES
The
.BR exit
function
never returns.
.SH SEE ALSO
.BR atexit (3),
.BR intro (3),
.BR tmpfile (3),
.BR sysexits (3)
.SH STANDARDS
The
.BR exit
function
conforms to ANSI/C. The
.BR _exit
function is defined by POSIX 1003.1-88.

157
usr.man/man3/fnmatch.3 Normal file
View File

@ -0,0 +1,157 @@
.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Guido van Rossum.
.\" 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.
.\"
.\" @(#)fnmatch.3 8.2 (Berkeley) 4/16/94
.\"
.TH FNMATCH 3 "22 February 1996" GNO "Library Routines"
.SH NAME
.BR fnmatch
\- match filename or pathname
.SH SYNOPSIS
#include <fnmatch.h>
.sp 1
int
\fBfnmatch\fR (const char *\fIpattern\fR, const char *\fIstring\fR,
int \fIflags\fR);
.SH DESCRIPTION
The
.BR fnmatch
function
matches patterns according to the rules used by the shell.
It checks the string specified by the
.I string
argument to see if it matches the pattern specified by the
.I pattern
argument.
.LP
The
.I flags
argument modifies the interpretation of
.I pattern
and
.IR string .
The value of
.I flags
is the bitwise inclusive
.BR OR
of any of the following
constants, which are defined in the include file <fnmatch.h>.
.RS
.IP FNM_NOESCAPE
Normally, every occurrence of a backslash
.BR \e
followed by a character in
.I pattern
is replaced by that character.
This is done to negate any special meaning for the character.
If the
.BR FNM_NOESCAPE
flag is set, a backslash character is treated as an ordinary character.
.IP FNM_PATHNAME
Slash characters in
.I string
must be explicitly matched by slashes in
.IR pattern .
If this flag is not set, then slashes are treated as regular characters.
.IP FNM_PERIOD
Leading periods in
.I string
must be explicitly matched by periods in
.IR pattern .
If this flag is not set, then leading periods are treated as regular
characters.
The definition of ``leading'' is related to the specification of
.BR FNM_PATHNAME.
A period is always ``leading'' if it is the first character in
.BR string .
Additionally, if
.BR FNM_PATHNAME
is set,
a period is ``leading'' if it immediately follows a slash.
.IP FNM_CASEFOLD
If this flag is set, then the filename matching will be case insensitive.
This is an extension for GNO.
.RE
.LP
In the GNO implementation, any colon
.RB ( : )
characters appearing in
.IR pattern
or
.IR string
will be mapped to slash
.RB ( / )
characters before any match is attempted, unless either
.IR pattern
or
.IR string
contain both colons and slashes.
.SH RETURN VALUES
The
.BR fnmatch
function returns zero if
.I string
matches the pattern specified by
.IR pattern ,
otherwise, it returns the value
.BR FNM_NOMATCH .
.SH BUGS
The pattern
.BR *
matches the empty string, even if
.BR FNM_PATHNAME
is specified.
.LP
This implementation of
.BR fnmatch
uses recursion. While this is not strictly a bug, it is a serious
limitation on the IIgs where stack space is at a premium.
.SH STANDARDS
Other than the mapping of
.BR :
characters to
.BR /
characters, the
.BR fnmatch
function conforms to POSIX 1003.2.
The
.BR FNM_CASEFOLD
flag is an extension to the standard.
.SH HISTORY
The
.BR fnmatch
function first appeared in 4.4BSD.
.SH SEE ALSO
.BR sh (1),
.BR glob (3),
.BR regex (3)

746
usr.man/man3/fts.3 Normal file
View File

@ -0,0 +1,746 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)fts.3 8.5 (Berkeley) 4/16/94
.\"
.TH FTS 3 "22 January 1997" GNO "Library Routines"
.SH NAME
.BR fts
\- traverse a file hierarchy
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <sys/stat.h>
.br
#include <fts.h>
.sp 1
FTS *\fBfts_open\fR (char * const *\fIpath_argv\fR, int \fIoptions\fR,
int (*\fIcompar\fR)(const FTSENT **, const FTSENT **));
.sp 1
FTSENT *\fBfts_read\fR (FTS *\fIftsp\fR);
.sp 1
FTSENT *\fBfts_children\fR (FTS *\fIftsp\fR, int \fIoptions\fR);
.sp 1
int \fBfts_set\fR (FTS \fIftsp\fR, FTSENT *\fIf\fR, int \fIoptions\fR);
.sp 1
int \fBfts_close\fR (FTS *\fIftsp\fR);
.SH DESCRIPTION
The
.BR fts
functions are provided for traversing UNIX file hierarchies.
A simple overview is that the
.BR fts_open
function returns a ``handle'' on a file hierarchy, which is then supplied to
the other
.BR fts
functions.
The function
.BR fts_read
returns a pointer to a structure describing one of the files in the file
hierarchy.
The function
.BR fts_children
returns a pointer to a linked list of structures, each of which describes
one of the files contained in a directory in the hierarchy.
In general, directories are visited two distinguishable times; in pre-order
(before any of their descendants are visited) and in post-order (after all
of their descendants have been visited).
Files are visited once.
It is possible to walk the hierarchy ``logically'' (ignoring symbolic links)
or physically (visiting symbolic links), order the walk of the hierarchy or
prune and/or re-visit portions of the hierarchy.
.LP
Two structures are defined (and typedef'd) in the include file <fts.h>.
The first is
.IR FTS ,
the structure that represents the file hierarchy itself.
The second is
.IR FTSENT ,
the structure that represents a file in the file
hierarchy.
Normally, an
.I FTSENT
structure is returned for every file in the file
hierarchy.
In this manual page, ``file'' and
.I "struct FTSENT"
are generally
interchangeable.
The
.I FTSENT
structure contains at least the following fields, which are
described in greater detail below:
.nf
typedef struct _ftsent {
u_short fts_info; /* flags for FTSENT structure */
char *fts_accpath; /* access path */
char *fts_path; /* root path */
short fts_pathlen; /* strlen(fts_path) */
char *fts_name; /* file name */
short fts_namelen; /* strlen(fts_name) */
short fts_level; /* depth (\-1 to N) */
int fts_errno; /* file errno */
long fts_number; /* local numeric value */
void *fts_pointer; /* local address value */
struct ftsent *fts_parent; /* parent directory */
struct ftsent *fts_link; /* next file structure */
struct ftsent *fts_cycle; /* cycle structure */
struct stat *fts_statp; /* stat(2) information */
} FTSENT;
.fi
.LP
These fields are defined as follows:
.RS
.IP fts_info
One of the following values describing the returned
.I FTSENT
structure and
the file it represents.
With the exception of directories without errors
.RB ( FTS_D ),
all of these
entries are terminal, that is, they will not be revisited, nor will any
of their descendants be visited.
.RS
.IP FTS_D
A directory being visited in pre-order.
.IP FTS_DC
A directory that causes a cycle in the tree.
(The
.I fts_cycle
field of the
.I FTSENT
structure will be filled in as well.)
.IP FTS_DEFAULT
Any
.I FTSENT
structure that represents a file type not explicitly described
by one of the other
.I fts_info
values.
.IP FTS_DNR
A directory which cannot be read.
This is an error return, and the
.I fts_errno
field will be set to indicate what caused the error.
.IP FTS_DOT
A file named
.BR \&.
or
.BR ..
which was not specified as a file name to
.BR fts_open
(see
.BR FTS_SEEDOT ) .
.IP FTS_DP
A directory being visited in post-order.
The contents of the
.I FTSENT
structure will be unchanged from when
it was returned in pre-order, i.e. with the
.I fts_info
field set to
.BR FTS_D .
.IP FTS_ERR
This is an error return, and the
.I fts_errno
field will be set to indicate what caused the error.
.IP FTS_F
A regular file.
.IP FTS_NS
A file for which no
.BR stat (2)
information was available.
The contents of the
.I fts_statp
field are undefined.
This is an error return, and the
.I fts_errno
field will be set to indicate what caused the error.
.IP FTS_NSOK
A file for which no
.BR stat (2)
information was requested.
The contents of the
.I fts_statp
field are undefined.
.IP FTS_SL
A symbolic link.
.IP FTS_SLNONE
A symbolic link with a non-existent target.
The contents of the
.I fts_statp
field reference the file characteristic information for the symbolic link
itself.
.RE
.IP fts_accpath
A path for accessing the file from the current directory.
.IP fts_path
The path for the file relative to the root of the traversal.
This path contains the path specified to
.BR fts_open
as a prefix.
.IP fts_pathlen
The length of the string referenced by
.RI ( fts_path )
.IP fts_name
The name of the file.
.IP fts_namelen
The length of the string referenced by
.RI ( fts_name )
.IP fts_level
The depth of the traversal, numbered from \-1 to N, where this file
was found.
The
.I FTSENT
structure representing the parent of the starting point (or root)
of the traversal is numbered \-1, and the
.I FTSENT
structure for the root
itself is numbered 0.
.IP fts_errno
Upon return of a
.I FTSENT
structure from the
.BR fts_children
or
.BR fts_read
functions, with its
.I fts_info
field set to
.BR FTS_DNR ,
.BR FTS_ERR
or
.BR FTS_NS ,
the
.I fts_errno
field contains the value of the external variable
.IR errno
specifying the cause of the error.
Otherwise, the contents of the
.I fts_errno
field are undefined.
.IP fts_number
This field is provided for the use of the application program and is
not modified by the
.BR fts
functions.
It is initialized to 0.
.IP fts_pointer
This field is provided for the use of the application program and is
not modified by the
.BR fts
functions.
It is initialized to
.BR NULL .
.IP fts_parent
A pointer to the
.I FTSENT
structure referencing the file in the hierarchy
immediately above the current file, i.e. the directory of which this
file is a member.
A parent structure for the initial entry point is provided as well,
however, only the
.RI ( fts_level )
.I fts_number
and
.I fts_pointer
fields are guaranteed to be initialized.
.IP fts_link
Upon return from the
.BR fts_children
function, the
.I fts_link
field points to the next structure in the NULL-terminated linked list of
directory members.
Otherwise, the contents of the
.I fts_link
field are undefined.
.IP fts_cycle
If a directory causes a cycle in the hierarchy (see
.BR FTS_DC ) ,
either because
of a hard link between two directories, or a symbolic link pointing to a
directory, the
.I fts_cycle
field of the structure will point to the
.I FTSENT
structure in the hierarchy that references the same file as the current
.I FTSENT
structure.
Otherwise, the contents of the
.I fts_cycle
field are undefined.
.IP fts_statp
A pointer to
.BR stat (2)
information for the file.
.RE
.LP
A single buffer is used for all of the paths of all of the files in the
file hierarchy.
Therefore, the
.I fts_path
and
.I fts_accpath
fields are guaranteed to be
.BR NULL -terminated
.IR only
for the file most recently returned by
.BR fts_read .
To use these fields to reference any files represented by other
.I FTSENT
structures will require that the path buffer be modified using the
information contained in that
.I FTSENT
structure's
.I fts_pathlen
field.
Any such modifications should be undone before further calls to
.BR fts_read
are attempted.
The
.I fts_name
field is always
.BR NULL -terminated.
.SH FTS_OPEN
The
.BR fts_open
function takes a pointer to an array of character pointers naming one
or more paths which make up a logical file hierarchy to be traversed.
The array must be terminated by a
.BR NULL
pointer.
.LP
There are
a number of options, at least one of which (either
.BR FTS_LOGICAL
or
.BR FTS_PHYSICAL )
must be specified.
The options are selected by
.IR or 'ing
the following values:
.RS
.IP FTS_COMFOLLOW
This option causes any symbolic link specified as a root path to be
followed immediately whether or not
.BR FTS_LOGICAL
is also specified.
.IP FTS_LOGICAL
This option causes the
.BR fts
routines to return
.I FTSENT
structures for the targets of symbolic links
instead of the symbolic links themselves.
If this option is set, the only symbolic links for which
.I FTSENT
structures
are returned to the application are those referencing non-existent files.
Either
.BR FTS_LOGICAL
or
.BR FTS_PHYSICAL
.IR must
be provided to the
.BR fts_open
function.
.IP FTS_NOCHDIR
As a performance optimization, the
.BR fts
functions change directories as they walk the file hierarchy.
This has the side-effect that an application cannot rely on being
in any particular directory during the traversal.
The
.BR FTS_NOCHDIR
option turns off this optimization, and the
.BR fts
functions will not change the current directory.
Note that applications should not themselves change their current directory
and try to access files unless
.BR FTS_NOCHDIR
is specified and absolute
pathnames were provided as arguments to
.BR fts_open .
.IP FTS_NOSTAT
By default, returned
.I FTSENT
structures reference file characteristic information (the
.I statp
field) for each file visited.
This option relaxes that requirement as a performance optimization,
allowing the
.BR fts
functions to set the
.I fts_info
field to
.BR FTS_NSOK
and leave the contents of the
.I statp
field undefined.
.IP FTS_PHYSICAL
This option causes the
.BR fts
routines to return
.I FTSENT
structures for symbolic links themselves instead
of the target files they point to.
If this option is set,
.I FTSENT
structures for all symbolic links in the
hierarchy are returned to the application.
Either
.BR FTS_LOGICAL
or
.BR FTS_PHYSICAL
.IR must
be provided to the
.BR fts_open
function.
.IP FTS_SEEDOT
By default, unless they are specified as path arguments to
.BR fts_open ,
any files named
.BR \&.
or
.BR ..
encountered in the file hierarchy are ignored.
This option causes the
.BR fts
routines to return
.I FTSENT
structures for them.
.IP FTS_XDEV
This option prevents
.BR fts
from descending into directories that have a different device number
than the file from which the descent began.
.RE
.LP
The argument
.BR compar
specifies a user-defined function which may be used to order the traversal
of the hierarchy.
It
takes two pointers to pointers to
.I FTSENT
structures as arguments and
should return a negative value, zero, or a positive value to indicate
if the file referenced by its first argument comes before, in any order
with respect to, or after, the file referenced by its second argument.
The
.RI ( fts_accpath )
.I fts_path
and
.I fts_pathlen
fields of the
.I FTSENT
structures may
.IR never
be used in this comparison.
If the
.I fts_info
field is set to
.BR FTS_NS
or
.BR FTS_NSOK ,
the
.I fts_statp
field may not either.
If the
.BR compar
argument is
.BR NULL ,
the directory traversal order is in the order listed in
.I path_argv
for the root paths, and in the order listed in the directory for
everything else.
.SH FTS_READ
The
.BR fts_read
function returns a pointer to an
.I FTSENT
structure describing a file in
the hierarchy.
Directories (that are readable and do not cause cycles) are visited at
least twice, once in pre-order and once in post-order.
All other files are visited at least once.
(Hard links between directories that do not cause cycles or symbolic
links to symbolic links may cause files to be visited more than once,
or directories more than twice.)
.LP
If all the members of the hierarchy have been returned,
.BR fts_read
returns
.BR NULL
and sets the external variable
.IR errno
to 0.
If an error unrelated to a file in the hierarchy occurs,
.BR fts_read
returns
.BR NULL
and sets
.IR errno
appropriately.
If an error related to a returned file occurs, a pointer to an
.I FTSENT
structure is returned, and
.IR errno
may or may not have been set (see
.RI ( fts_info )
.LP
The
.I FTSENT
structures returned by
.BR fts_read
may be overwritten after a call to
.BR fts_close
on the same file hierarchy stream, or, after a call to
.BR fts_read
on the same file hierarchy stream unless they represent a file of type
directory, in which case they will not be overwritten until after a call to
.BR fts_read
after the
.I FTSENT
structure has been returned by the function
.BR fts_read
in post-order.
.SH FTS_CHILDREN
The
.BR fts_children
function returns a pointer to an
.I FTSENT
structure describing the first entry in a NULL-terminated linked list of
the files in the directory represented by the
.I FTSENT
structure most recently returned by
.BR fts_read .
The list is linked through the
.I fts_link
field of the
.I FTSENT
structure, and is ordered by the user-specified comparison function, if any.
Repeated calls to
.BR fts_children
will recreate this linked list.
.LP
As a special case, if
.BR fts_read
has not yet been called for a hierarchy,
.BR fts_children
will return a pointer to the files in the logical directory specified to
.BR fts_open ,
i.e. the arguments specified to
.BR fts_open .
Otherwise, if the
.I FTSENT
structure most recently returned by
.BR fts_read
is not a directory being visited in pre-order,
or the directory does not contain any files,
.BR fts_children
returns
.BR NULL
and sets
.IR errno
to zero.
If an error occurs,
.BR fts_children
returns
.BR NULL
and sets
.IR errno
appropriately.
.LP
The
.I FTSENT
structures returned by
.BR fts_children
may be overwritten after a call to
.BR fts_children ,
.BR fts_close
or
.BR fts_read
on the same file hierarchy stream.
.LP
.IR Option
may be set to the following value:
.RS
.IP FTS_NAMEONLY
Only the names of the files are needed.
The contents of all the fields in the returned linked list of structures
are undefined with the exception of the
.I fts_name
and
.I fts_namelen
fields.
.RE
.SH FTS_SET
The function
.BR fts_set
allows the user application to determine further processing for the
file
.I f
of the stream
.RI ( ftsp )
The
.BR fts_set
function
returns 0 on success, and \-1 if an error occurs.
.IR Option
must be set to one of the following values:
.RS
.IP FTS_AGAIN
Re-visit the file; any file type may be re-visited.
The next call to
.BR fts_read
will return the referenced file.
The
.I fts_stat
and
.I fts_info
fields of the structure will be reinitialized at that time,
but no other fields will have been changed.
This option is meaningful only for the most recently returned
file from
.BR fts_read .
Normal use is for post-order directory visits, where it causes the
directory to be re-visited (in both pre and post-order) as well as all
of its descendants.
.IP FTS_FOLLOW
The referenced file must be a symbolic link.
If the referenced file is the one most recently returned by
.BR fts_read ,
the next call to
.BR fts_read
returns the file with the
.I fts_info
and
.I fts_statp
fields reinitialized to reflect the target of the symbolic link instead
of the symbolic link itself.
If the file is one of those most recently returned by
.BR fts_children ,
the
.I fts_info
and
.I fts_statp
fields of the structure, when returned by
.BR fts_read ,
will reflect the target of the symbolic link instead of the symbolic link
itself.
In either case, if the target of the symbolic link does not exist the
fields of the returned structure will be unchanged and the
.I fts_info
field will be set to
.BR FTS_SLNONE .
.LP
If the target of the link is a directory, the pre-order return, followed
by the return of all of its descendants, followed by a post-order return,
is done.
.IP FTS_SKIP
No descendants of this file are visited.
The file may be one of those most recently returned by either
.BR fts_children
or
.BR fts_read .
.RE
.SH FTS_CLOSE
The
.BR fts_close
function closes a file hierarchy stream
.I ftsp
and restores the current directory to the directory from which
.BR fts_open
was called to open
.RI ( ftsp )
The
.BR fts_close
function
returns 0 on success, and \-1 if an error occurs.
.SH ERRORS
The function
.BR fts_open
may fail and set
.IR errno
for any of the errors specified for the library functions
.BR open (2)
and
.BR malloc (3).
.LP
The function
.BR fts_close
may fail and set
.IR errno
for any of the errors specified for the library functions
.BR chdir (2)
and
.BR close (2).
.LP
The functions
.BR fts_read
and
.BR fts_children
may fail and set
.IR errno
for any of the errors specified for the library functions
.BR chdir (2),
.BR malloc (3),
.BR opendir (3),
.BR readdir (3)
and
.BR stat (2).
.LP
In addition,
.BR fts_children ,
.BR fts_open
and
.BR fts_set
may fail and set
.IR errno
as follows:
.RS
.IP \fBEINVAL\fR
The options were invalid.
.RE
.SH SEE ALSO
.BR find (1),
.BR chdir (2),
.BR stat (2),
.BR qsort (3)
.SH STANDARDS
The
.BR fts
utility is expected to be included in a future
POSIX 1003.1-88 revision.

155
usr.man/man3/getcwd.3 Normal file
View File

@ -0,0 +1,155 @@
.\" Copyright (c) 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.
.\"
.\" @(#)getcwd.3 8.2 (Berkeley) 12/11/93
.\"
.TH GETCWD 3 "18 December 1996" GNO "Library Routines"
.SH NAME
.BR getcwd ,
.BR getwd
\- get working directory pathname
.SH SYNOPSIS
#include <unistd.h>
.sp 1
char *
\fBgetcwd\fR (char *\fIbuf\fR, size_t \fIsize\fR);
.br
char *
\fBgetwd\fR (char *\fIbuf\fR);
.SH DESCRIPTION
The
.BR getcwd
function copies the absolute pathname of the current working directory
(GS/OS prefix 0 if not NULL, otherwise GS/OS prefix 8)
into the memory referenced by
.I buf
and returns a pointer to
.IR buf .
The
.I size
argument is the size, in bytes, of the array referenced by
.IR buf .
.LP
If
.I buf
is
.BR NULL ,
space is allocated as necessary to store the pathname.
This space may later be released by
.BR free (3).
.LP
The function
.BR getwd
is a compatibility routine which calls
.BR getcwd
with its
.I buf
argument and a size of
.BR MAXPATHLEN
(as defined in the include file
.BR <sys/param.h> ).
Obviously,
.I buf
should be at least
.BR MAXPATHLEN
bytes in length.
.LP
These routines make use of the
.BR _mapPath (3)
facility.
.SH RETURN VALUES
Upon successful completion, a pointer to the pathname is returned.
Otherwise a
.BR NULL
pointer is returned and the global variable
.IR errno
is set to indicate the error.
In addition,
.BR getwd
copies the error message associated with
.IR errno
into the memory referenced by
.IR buf .
.SH COMPATIBILITY
These routines are thread safe.
.SH ERRORS
The
.BR getcwd
function
will fail if:
.RS
.IP \fBEACCESS\fR
Read or search permission was denied for a component of the pathname.
.IP \fBEINVAL\fR
The
.I size
argument is zero, or if pathname mapping is active and the current working
directory has a component which includes the slash ('/') character. See
.BR _mapPath (3).
.IP \fBENOENT\fR
A component of the pathname no longer exists.
.IP \fBENOMEM\fR
Insufficient memory is available.
.IP \fBERANGE\fR
The
.I size
argument is greater than zero but smaller than the length of the pathname
plus 1.
.RE
.SH BUGS
The
.BR getwd
function
does not do sufficient error checking and is not able to return very
long, but valid, paths.
It is provided for compatibility and should be avoided when possible.
.SH STANDARDS
The
.BR getcwd
function
conforms to
.BR "ANSI C" .
The ability to specify a
.BR NULL
pointer and have
.BR getcwd
allocate memory as necessary is an extension.
.SH HISTORY
The
.BR getwd
function appeared in
BSD 4.0.
.SH SEE ALSO
.BR chdir (2),
.BR fchdir (2),
.BR _mapPath (3),
.BR malloc (3),
.BR strerror (3)

215
usr.man/man3/getenv.3 Normal file
View File

@ -0,0 +1,215 @@
.\" Portions of this code (where listed) are:
.\"
.\" Copyright (c) 1988, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" 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.
.\"
.\" from: @(#)getenv.3 6.11 (Berkeley) 6/29/91
.\" getenv.3,v 1.2 1993/08/01 07:44:27 mycroft Exp
.\"
.\" This man page was modified to conform with the lenviron v1.1.3
.\" release for GNO v2.0.3 by Devin Reade <gdr@myrias.com>. lenviron
.\" was superceeded by libc as of GNO v2.0.6.
.\"
.TH GETENV 3 "29 January 1997" GNO "Library Functions"
.SH NAME
.LP
.BR getenv ,
.BR putenv ,
.BR setenv ,
.BR unsetenv ,
.BR environInit ,
.BR environPop ,
.BR environPush ,
\- environment variable functions
.SH SYNOPSIS
#include <stdlib.h>
.sp 1
char *\fBgetenv\fR (const char *\fIname\fR);
.br
int \fBputenv\fR (const char *\fIstring\fR);
.br
int \fBsetenv\fR (const char *\fIname\fR, const char *\fIvalue\fR
int \fIoverwrite\fR);
.br
void \fBunsetenv\fR (const char *\fIname\fR);
.sp 1
int \fBenvironInit\fR (void);
.br
int \fBenvironPush\fR (void);
.br
void \fBenvironPop\fR (void);
.SH DESCRIPTION
These functions set, unset and fetch environment variables from the host
.IR "environment list" .
For compatibility with differing environment conventions, the given arguments
.I name
and
.I value
may be appended and prepended, respectively, with an equal sign.
.LP
The
.B getenv
function obtains the current value of the environment variable,
.IR name .
If the variable
.I name
is not in the current environment, a null pointer is returned.
.LP
The
.B setenv
function inserts or resets the environment variable
.I name
in the current environment list. If the variable
.I name
does not exist in the list, it is inserted with the given
.I value.
If the variable does exist, the argument
.I overwrite
is tested; if
.I overwrite
is zero, the variable is not reset, otherwise it is reset to the given
.I value.
.LP
The
.B putenv
function performs the equivalent of:
.nf
setenv(\fIname\fR, \fIvalue\fR, 1);
.fi
and expects
.I string
to be of the form
.IR name=value .
.LP
The
.B unsetenv
function deletes all instances of the variable name pointed to by
.I name
from the list.
.LP
The
.BR environInit ,
.BR environPush ,
and
.BR environPop
functions are non\-standard (GNO-specific).
.LP
The
.B environInit
function is used to initialize the
.B environ
variable, since this functionality is provided by neither shell. It
is necessary to use
.B environInit
before any explicit references to \fIenviron\fR, but if \fIenviron\fR is
not to be referenced, it is not necessary to call
.B environInit
at all.
.LP
.B environPush
and
.B environPop
are used to push and pop, respectively, the environment stack. See
.B environ
(8) for more information.
.SH RETURN VALUES
The functions
.BR environInit ,
.BR environPush ,
.BR putenv ,
and
.BR setenv
return zero if successful; otherwise the global variable
.B errno
is set to indicate the error and a \-1 is returned.
.SH ERRORS
.IP \fBENOMEM\fR
The functions
.BR environInit ,
.BR environPush ,
.BR putenv ,
or
.BR setenv
failed because they were unable to allocate memory for the environment.
.SH CAVEATS
If
.B environ
has been modified without using the library routines, then the internal
shell variables and the shell environment represented by
.B environ
will not be consistent. Also, since environ entries are dynamically
allocated and freed, modifying those entries without using the library
routines may result in memory trashing and unpredicable behavior.
.SH AUTHORS
These routines were written for GNO primarily by Devin Reade. They
also contain code fragments from Dave Tribby and James Brookes.
.LP
These routines also contains code is derived from software contributed
to Berkeley by the American National Standards Committee X3, on
Information Processing Systems.
.SH SEE ALSO
.BR gsh (1),
.BR sh (1),
.BR execve (2),
.BR environ (7),
.SH HISTORY
The functions
.B setenv
and
.B unsetenv
appeared in v7. The
.B putenv
function appeared in 4.3BSD (Reno).
.LP
The first appearance of these routines for GNO was as part of the
(now superceeded)
.BR lenviron
library. They were formally incorporated into GNO as of v2.0.6.
These routines are no longer guaranteed to be compatible with the
ORCA/Shell.
.LP
The functions
.BR environInit ,
.BR environPush ,
and
.BR environPop
were previously
.BR initenv ,
.BR pushenv ,
and
.BR popenv ,
respectively.

212
usr.man/man3/getgrent.3 Normal file
View File

@ -0,0 +1,212 @@
.\" Copyright (c) 1989, 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.
.\"
.\" From: @(#)getgrent.3 8.2 (Berkeley) 4/19/94
.\" $Id: getgrent.3,v 1.1 1997/02/27 07:32:22 gdr Exp $
.\"
.TH GETGRENT 3 "27 January 1997" GNO "Library Routines"
.SH NAME
.BR getgrent ,
.BR getgrnam ,
.BR getgrgid ,
.BR setgroupent ,
.BR setgrent ,
.BR endgrent
\- group database operations
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <grp.h>
.sp 1
struct group *
\fBgetgrent\fR (void);
.br
struct group *
\fBgetgrnam\fR (const char *\fIname\fR);
.br
struct group *
\fBgetgrgid\fR (gid_t \fIgid\fR);
.br
int
\fBsetgroupent\fR (int \fIstayopen\fR);
.br
int
\fBsetgrent\fR (void);
.br
void
\fBendgrent\fR (void);
.SH DESCRIPTION
These functions operate on the group database file
.BR /etc/group
which is described
in
.BR group (5).
Each line of the database is defined by the structure
.BR group
found in the include
file <grp.h>:
.nf
struct group {
char *gr_name; /* group name */
char *gr_passwd; /* group password */
gid_t gr_gid; /* group id */
char **gr_mem; /* group members */
};
.fi
Applications should never read
.BR /etc/group
directly, as the implementation of the group database is subject
to change.
.LP
The functions
.BR getgrnam
and
.BR getgrgid
search the group database for the given group name pointed to by
.BR name
or the group id
.BR gid ,
respectively, returning the first one encountered. Identical group
names or group gids may result in undefined behavior.
.LP
The
.BR getgrent
function
sequentially reads the group database and is intended for programs
that wish to step through the complete list of groups.
.LP
All three routines will open the group file for reading, if necessary.
.LP
The
.BR setgroupent
function
opens the file, or rewinds it if it is already open. If
.I stayopen
is non-zero, file descriptors are left open, significantly speeding
functions subsequent calls. This functionality is unnecessary for
.BR getgrent
as it doesn't close its file descriptors by default. It should also
be noted that it is dangerous for long-running programs to use this
functionality as the group file may be updated.
.LP
The
.BR setgrent
function
is identical to
.BR setgroupent
with an argument of zero.
.LP
The
.BR endgrent
function
closes any open files.
.SH YP/NIS INTERACTION
When the
.BR yp (4)
group database is enabled, the
.BR getgrnam
and
.BR getgrgid
functions use the YP maps
.BR group.byname
and
.BR group.bygid ,
respectively, if the requested group is not found in the local
.BR /etc/group
file. The
.BR getgrent
function will step through the YP map
.BR group.byname
if the entire map is enabled as described in
.BR group (5).
.SH RETURN VALUES
The functions
.BR getgrent ,
.BR getgrnam ,
and
.BR getgrgid ,
return a pointer to the group entry if successful; if end-of-file
is reached or an error occurs a null pointer is returned.
The functions
.BR setgroupent
and
.BR setgrent
return the value 1 if successful, otherwise the value
0 is returned.
The functions
.BR endgrent
and
.BR setgrfile
have no return value.
.SH FILES
.IP \fB/etc/group\fR
group database file
.SH SEE ALSO
.BR getpwent 3 ,
.BR group 5 ,
.BR yp 4
.SH HISTORY
The functions
.BR endgrent ,
.BR getgrent ,
.BR getgrnam ,
.BR getgrgid ,
and
.BR setgrent
appeared in v7.
The functions
.BR setgrfile
and
.BR setgroupent
appeared in 4.3BSD (Reno).
.SH COMPATIBILITY
The historic function
.BR setgrfile ,
which allowed the specification of alternate password databases, has
been deprecated and is no longer available.
.SH BUGS
The functions
.BR getgrent ,
.BR getgrnam ,
.BR getgrgid ,
.BR setgroupent
and
.BR setgrent
leave their results in an internal static object and return
a pointer to that object. Subsequent calls to
the same function
will modify the same object.
.LP
GNO does not currently make use of the
.BR yp (4)
database.

93
usr.man/man3/gethostname.3 Normal file
View File

@ -0,0 +1,93 @@
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)gethostname.3 8.1 (Berkeley) 6/4/93
.\"
.TH GETHOSTNAME 3 "25 February 1997" GNO "Library Routines"
.SH NAME
.BR gethostname ,
.BR sethostname
\- get/set name of current host
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int \fBgethostname\fR (char *\fIname\fR, int \fInamelen\fR);
.br
int \fBsethostname\fR (const char *\fIname\fR, int \fInamelen\fR);
.SH DESCRIPTION
.BR Gethostname
returns the standard host name for the current processor, as
previously set by
.BR sethostname .
The parameter
.I namelen
specifies the size of the
.I name
array. The returned name is null-terminated unless insufficient
space is provided.
.LP
.BR Sethostname
sets the name of the host machine to be
.IR name ,
which has length
.IR namelen .
This call is restricted to the super-user and
is normally used only when the system is bootstrapped.
.SH RETURN VALUES
If the call succeeds a value of 0 is returned. If the call
fails, a value of -1 is returned and an error code is
placed in the global location
.IR errno .
.SH ERRORS
The following errors may be returned by these calls:
.RS
.IP \fBEFAULT\fR
The
.I name
or
.I namelen
parameter gave an
invalid address.
.IP \fBEPERM\fR
The caller tried to set the hostname and was not the super-user.
.RE
.SH SEE ALSO
.BR gethostid (3),
.BR sysctl (3)
.SH BUGS
Host names are limited to
.BR MAXHOSTNAMELEN
(from <sys/param.h)
characters, currently 256.
.SH HISTORY
The
.BR sethostname
function call appeared in 4.2BSD.

289
usr.man/man3/getopt.3 Normal file
View File

@ -0,0 +1,289 @@
.\" Copyright (c) 1988, 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.
.\"
.\" @(#)getopt.3 8.4 (Berkeley) 4/19/94
.\"
.TH GETOPT 3 "26 January 1997" GNO "Library Routines"
.SH NAME
.BR getopt
\- get option character from command line argument list
.SH SYNOPSIS
#include <stdlib.h>
.sp 1
extern char *\fBoptarg\fR;
.br
extern int \fBoptind\fR;
.br
extern int \fBoptopt\fR;
.br
extern int \fBopterr\fR;
.br
extern int \fBoptreset\fR;
.sp 1
int
\fBgetopt\fR (int \fIargc\fR, char * const *\fIargv\fR,
const char *\fIoptstring\fR);
.br
int \fBgetopt_restart\fR (void);
.SH DESCRIPTION
This manual page describes the BSD implementation of
.BR getopt .
.LP
The
.BR getopt
function incrementally parses a command line argument list
.I argv
and returns the next
.IR known
option character.
An option character is
.IR known
if it has been specified in the string of accepted option characters,
.IR optstring .
.LP
The option string
.I optstring
may contain the following elements: individual characters, and
characters followed by a colon to indicate an option argument
is to follow.
For example, an option string
.IR x
recognizes an option
.BR -x ,
and an option string
.BR x:
recognizes an option and argument
.BR "-x argument" .
It does not matter to
.BR getopt
if a following argument has leading white space.
.LP
On return from
.BR getopt ,
.IR optarg
points to an option argument, if it is anticipated,
and the variable
.IR optind
contains the index to the next
.I argv
argument for a subsequent call
to
.BR getopt .
The variable
.IR optopt
saves the last
.IR known
option character returned by
.BR getopt .
.LP
The variable
.IR opterr
and
.IR optind
are both initialized to 1.
The
.IR optind
variable may be set to another value before a set of calls to
.BR getopt
in order to skip over more or less argv entries.
.LP
In order to use
.BR getopt
to evaluate multiple sets of arguments, or to evaluate a single set of
arguments multiple times,
the variable
.IR optreset
must be set to 1 before the second and each additional set of calls to
.BR getopt ,
and the variable
.IR optind
must be reinitialized.
.LP
The
.BR getopt
function
returns an
.BR EOF
when the argument list is exhausted, or a non-recognized
option is encountered.
The interpretation of options in the argument list may be canceled
by the option
.BR "--"
(double dash) which causes
.BR getopt
to signal the end of argument processing and return an
.BR EOF .
When all options have been processed (i.e., up to the first non-option
argument),
.BR getopt
returns
.BR EOF .
.LP
The
.BR getopt_restart
function sets
.BR optreset
and
.BR optind
to 1 and returns zero. It is provided for backwards compatibility
with older versions of GNO, and should be avoided in new code.
.SH DIAGNOSTICS
If the
.BR getopt
function encounters a character not found in the string
.IR optarg
or detects
a missing option argument it writes an error message and returns
.BR ?
to the
.IR stderr .
Setting
.IR opterr
to a zero will disable these error messages.
If
.IR optstring
has a leading
.BR \&:
then a missing option argument causes a
.BR \&:
to be returned in addition to suppressing any error messages.
.LP
Option arguments are allowed to begin with
.BR \- ;
this is reasonable but
reduces the amount of error checking possible.
.SH EXTENSIONS
The
.IR optreset
variable was added to make it possible to call the
.BR getopt
function multiple times.
This is an extension to the POSIX 1003.2 specification.
.LP
The
.BR getopt_reset
function is also an extension, but one that has been deprecated.
.SH LIMITATIONS
This implementation of
.BR getopt
does not allow one to mix options and non-option arguments; option
processing will halt as soon as the first non-option argument is
found. The GNU implementation does not have this limitation, but also
cannot be restarted. The GNU implementation also allows "long options",
where the option name may be more than one character.
.LP
See the GNO FAQ regarding availability of the GNU implementation of
.BR getopt
and
.BR getopt_long (3)
for GNO.
.SH EXAMPLE
.nf
extern char *optarg;
extern int optind;
int bflag, ch, fd;
bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != EOF)
switch(ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
(void)fprintf(stderr,
"myname: %s: %s\en", optarg, strerror(errno));
exit(1);
}
break;
case '?':
default:
usage();
}
argc -= optind;
argv += optind;
.fi
.SH HISTORY
The
.BR getopt
function appeared 4.3BSD.
.SH BUGS
A single dash
.BR \-
may be specified as an character in
.IR optstring ,
however it should
.IR never
have an argument associated with it.
This allows
.BR getopt
to be used with programs that expect
.BR \-
as an option flag.
This practice is wrong, and should not be used in any current development.
It is provided for backward compatibility
.IR only .
By default, a single dash causes
.BR getopt
to return
.BR EOF .
This is, we believe, compatible with System V.
.LP
It is also possible to handle digits as option letters.
This allows
.BR getopt
to be used with programs that expect a number (such as
.BR \-3 )
as an option.
This practice is wrong, and should not be used in any current development.
It is provided for backward compatibility
.IR only .
The following code fragment works in most cases.
.nf
int length;
char *p;
while ((c = getopt(argc, argv, "0123456789")) != EOF)
switch (c) {
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
p = argv[optind - 1];
if (p[0] == '-' && p[1] == ch && !p[2])
length = atoi(++p);
else
length = atoi(argv[optind] + 1);
break;
}
}
.fi
.SH SEE ALSO
.BR getsubopt (3),
.BR getopt_long (3G).

86
usr.man/man3/getpass.3 Normal file
View File

@ -0,0 +1,86 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)getpass.3 8.1 (Berkeley) 6/4/93
.\"
.TH GETPASS 3 "25 February 1997" GNO "Library Routines"
.SH NAME
.BR getpass
\- get a password
.SH SYNOPSIS
#include <pwd.h>
.br
#include <unistd.h>
.sp 1
char *\fBgetpass\fR (const char *\fIprompt\fR);
.SH DESCRIPTION
The
.BR getpass
function displays a prompt to, and reads in a password from,
.BR \&.tty .
If this device is not accessible,
.BR getpass
displays the prompt on the standard error output and reads from the standard
input.
.LP
The password may be up to _PASSWORD_LEN (currently 128)
characters in length.
Any additional
characters and the terminating newline character are discarded.
.LP
.BR Getpass
turns off character echoing while reading the password.
.LP
.SH RETURN VALUES
.BR Getpass
returns a pointer to the null terminated password.
.SH SEE ALSO
.BR crypt (3)
.SH HISTORY
A
.BR getpass
function appeared in v7.
.SH BUGS
The
.BR getpass
function leaves its result in an internal static object and returns
a pointer to that object.
Subsequent calls to
.BR getpass
will modify the same object.
.LP
The calling process should zero the password as soon as possible to
avoid leaving the cleartext password visible in the process's address
space.
.LP
Upon receipt of a SIGTSTP, the input buffer will be flushed, so any
partially typed password must be retyped when the process
continues.

213
usr.man/man3/getpwent.3 Normal file
View File

@ -0,0 +1,213 @@
.\" Copyright (c) 1988, 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.
.\"
.\" From: @(#)getpwent.3 8.2 (Berkeley) 12/11/93
.\"
.TH GETPWENT 3 "September 20, 1994" "" "Library Routines"
.SH NAME
.BR getpwent ,
.BR getpwnam ,
.BR getpwuid ,
.BR setpassent ,
.BR setpwent ,
.BR endpwent
\- password database operations
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <pwd.h>
.sp 1
struct passwd *\fBgetpwent\fR (void);
.br
struct passwd *\fBgetpwnam\fR (const char *\fIlogin\fR);
.br
struct passwd *\fBgetpwuid\fR (uid_t \fIuid\fR);
.br
int \fBsetpassent\fR (int \fIstayopen\fR);
.br
int \fBsetpwent\fR (void);
.br
void \fBendpwent\fR (void);
.SH DESCRIPTION
These functions
operate on the password database file
which is described
in
.BR passwd (5).
Each entry in the database is defined by the structure
.BR passwd
found in the include
file <pwd.h>:
.nf
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
uid_t pw_uid; /* user uid */
gid_t pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user access class */
char *pw_gecos; /* real name */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
.fi
.LP
The functions
.BR getpwnam
and
.BR getpwuid
search the password database for the given login name or user uid,
respectively, always returning the first one encountered.
.LP
The
.BR getpwent
function
sequentially reads the password database and is intended for programs
that wish to process the complete list of users.
.LP
The
.BR setpassent
function
accomplishes two purposes.
First, it causes
.BR getpwent
to ``rewind'' to the beginning of the database.
Additionally, if
.I stayopen
is non-zero, file descriptors are left open, significantly speeding
up subsequent accesses for all of the routines.
(This latter functionality is unnecessary for
.BR getpwent
as it doesn't close its file descriptors by default.)
.LP
It is dangerous for long-running programs to keep the file descriptors
open as the database will become out of date if it is updated while the
program is running.
.LP
The
.BR setpwent
function
is identical to
.BR setpassent
with an argument of zero.
.LP
The
.BR endpwent
function
closes any open files.
.LP
These routines have been written to ``shadow'' the password file, e.g.
allow only certain programs to have access to the encrypted password.
If the process which calls them has an effective uid of 0, the encrypted
password will be returned, otherwise, the password field of the returned
structure will point to the string
.BR * .
.SH YP/NIS INTERACTION
When the
.BR yp (4)
password database is enabled, the
.BR getpwnam
and
.BR getpwuid
functions use the YP maps
.BR passwd.byname
and
.BR passwd.byuid ,
respectively, if the requested password entry is not found in the
local database. The
.BR getpwent
function will step through the YP map
.BR passwd.byname
if the entire map is enabled as described in
.BR passwd (5).
.SH RETURN VALUES
The functions
.BR getpwent ,
.BR getpwnam ,
and
.BR getpwuid ,
return a valid pointer to a passwd structure on success
and a null pointer if end-of-file is reached or an error occurs.
The functions
.BR setpassent
and
.BR setpwent
return 0 on failure and 1 on success.
The
.BR endpwent
function
has no return value.
.SH FILES
.IP \fB/etc/pwd.db\fR
The insecure password database file
.IP \fB/etc/spwd.db\fR
The secure password database file
.IP \fB/etc/master.passwd\fR
The current password file
.IP \fB/etc/passwd\fR
A Version 7 format password file
.SH SEE ALSO
.BR getlogin (2),
.BR getgrent (3),
.BR yp (4),
.BR passwd (5),
.BR pwd_mkdb (8),
.BR vipw (8)
.SH HISTORY
The
.BR getpwent ,
.BR getpwnam ,
.BR getpwuid ,
.BR setpwent,
and
.BR endpwent
functions appeared in v7.
The
.BR setpassent
function appeared in 4.3 Reno.
.SH COMPATIBILITY
The historic function
.BR setpwfile (3),
which allowed the specification of alternate password databases,
has been deprecated and is no longer available.
.SH BUGS
The functions
.BR getpwent ,
.BR getpwnam ,
and
.BR getpwuid ,
leave their results in an internal static object and return
a pointer to that object. Subsequent calls to
the same function
will modify the same object.

143
usr.man/man3/getsubopt.3 Normal file
View File

@ -0,0 +1,143 @@
.\" Copyright (c) 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.
.\"
.\" @(#)getsubopt.3 8.1 (Berkeley) 6/9/93
.\"
.TH GETSUBOPT 3 "22 February 1997" GNO "Library Routines"
.SH NAME
.BR getsubopt
\- get sub options from an argument
.SH SYNOPSIS
#include <stdlib.h>
.sp 1
extern char *\fBsuboptarg\fR;
.sp 1
int
\fBgetsubopt\fR (char **\fIoptionp\fR, char * const *\fItokens\fR, char **\fIvaluep\fR);
.SH DESCRIPTION
The
.BR getsubopt
function
parses a string containing tokens delimited by one or more tab, space or
comma characters.
It is intended for use in parsing groups of option arguments provided
as part of a utility command line.
.LP
The argument
.I optionp
is a pointer to a pointer to the string.
The argument
.I tokens
is a pointer to a
.BR NULL Ns -terminated
array of pointers to strings.
.LP
The
.BR getsubopt
function
returns the zero-based offset of the pointer in the
.I tokens
array referencing a string which matches the first token
in the string, or, \-1 if the string contains no tokens or
.I tokens
does not contain a matching string.
.LP
If the token is of the form ``name=value'', the location referenced by
.I valuep
will be set to point to the start of the ``value'' portion of the token.
.LP
On return from
.BR getsubopt ,
.I optionp
will be set to point to the start of the next token in the string,
or the null at the end of the string if no more tokens are present.
The external variable
.I suboptarg
will be set to point to the start of the current token, or
.BR NULL
if no
tokens were present.
The argument
.I valuep
will be set to point to the ``value'' portion of the token, or
.BR NULL
if no ``value'' portion was present.
.SH EXAMPLE
.nf
char *tokens[] = {
#define ONE 0
"one",
#define TWO 1
"two",
NULL
};
\&...
extern char *optarg, *suboptarg;
char *options, *value;
while ((ch = getopt(argc, argv, "ab:")) != \-1) {
switch(ch) {
case 'a':
/* process ``a'' option */
break;
case 'b':
options = optarg;
while (*options) {
switch(getsubopt(&options, tokens, &value)) {
case ONE:
/* process ``one'' sub option */
break;
case TWO:
/* process ``two'' sub option */
if (!value)
error("no value for two");
i = atoi(value);
break;
case \-1:
if (suboptarg)
error("illegal sub option %s",
suboptarg);
else
error("missing sub option");
break;
}
break;
}
.fi
.SH SEE ALSO
.BR getopt (3),
.BR strsep (3)
.SH HISTORY
The
.BR getsubopt
function first appeared in 4.4BSD.

176
usr.man/man3/getttyent.3 Normal file
View File

@ -0,0 +1,176 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)getttyent.3 8.1 (Berkeley) 6/4/93
.\"
.TH GETTTYENT 3 "23 February 1996" GNO "Library Routines"
.SH NAME
.BR getttyent ,
.BR getttynam ,
.BR setttyent ,
.BR endttyent
\- get ttys file entry
.SH SYNOPSIS
.br
#include <ttyent.h>
.sp 1
struct ttyent *\fBgetttyent\fR (void);
.br
struct ttyent *\fBgetttynam\fR (char *\fIname\fR);
.br
int \fBsetttyent\fR (void);
.br
int \fBendttyent\fR (void);
.SH DESCRIPTION
The
.BR getttyent ,
and
.BR getttynam
functions
each return a pointer to an object, with the following structure,
containing the broken-out fields of a line from the tty description
file.
.nf
struct ttyent {
char *ty_name; /* terminal device name */
char *ty_getty; /* command to execute */
char *ty_type; /* terminal type */
#define TTY_ON 0x01 /* enable logins */
#define TTY_SECURE 0x02 /* allow uid of 0 to login */
int ty_status; /* flag values */
char *ty_window; /* command for window manager */
char *ty_comment; /* comment field */
};
.fi
.LP
The fields are as follows:
.RS
.IP ty_name
The name of the character-special file.
.IP ty_getty
The name of the command invoked by
.BR init (8)
to initialize tty line characteristics.
.IP ty_type
The name of the default terminal type connected to this tty line.
.IP ty_status
A mask of bit fields which indicate various actions allowed on this
tty line.
The possible flags are as follows:
.RS
.IP TTY_ON
Enables logins (i.e.,
.BR init (8)
will start the command referenced by
.I ty_getty
on this entry).
.IP TTY_SECURE
Allow users with a uid of 0 to login on this terminal.
.RE
.IP ty_window
The command to execute for a window system associated with the line.
.IP ty_comment
Any trailing comment field, with any leading hash marks (``#'') or
whitespace removed.
.RE
.LP
If any of the fields pointing to character strings are unspecified,
they are returned as null pointers.
The field
.I ty_status
will be zero if no flag values are specified.
.LP
See
.BR ttys (5)
for a more complete discussion of the meaning and usage of the
fields.
.LP
The
.BR getttyent
function
reads the next line from the ttys file, opening the file if necessary.
The
.BR setttyent
function
rewinds the file if open, or opens the file if it is unopened.
The
.BR endttyent
function
closes any open files.
.LP
The
.BR getttynam
function
searches from the beginning of the file until a matching
.I name
is found
(or until
.BR EOF
is encountered).
.SH RETURN VALUES
The routines
.BR getttyent
and
.BR getttynam
return a null pointer on
.BR EOF
or error.
The
.BR setttyent
function
and
.BR endttyent
return 0 on failure and 1 on success.
.SH FILES
.RS
.BR /etc/ttys
.RE
.SH SEE ALSO
.BR login (1),
.BR ttyslot (3),
.BR gettytab (5),
.BR termcap (5),
.BR ttys (5),
.BR getty (8),
.BR init (8)
.SH HISTORY
The
.BR getttyent ,
.BR getttynam ,
.BR setttyent ,
and
.BR endttyent
functions appeared in 4.3BSD.
.SH BUGS
These functions use static data storage;
if the data is needed for future use, it should be
copied before any subsequent calls overwrite it.

95
usr.man/man3/index.3 Normal file
View File

@ -0,0 +1,95 @@
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\" 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.
.\"
.\" @(#)index.3 8.1 (Berkeley) 6/4/93
.\"
.TH INDEX 3 "27 January 1997" GNO "Library Routines"
.SH NAME
.BR index ,
.BR rindex
\- locate character in string
.SH SYNOPSIS
#include <string.h>
.sp 1
char *
\fBindex\fR (const char *\fIs\fR, int \fIc\fR);
.br
char *
\fBrindex\fR (const char *\fIs\fR, int \fIc\fR);
.SH DESCRIPTION
The
.BR index
function
locates the first character matching
.I c
(converted to a
.IR char )
in the null-terminated string
.IR s .
.LP
The
.BR rindex
function
locates the last character
matching
.I c
(converted to a
.IR char )
in the null-terminated string
.IR s .
.SH RETURN VALUES
A pointer to the character is returned if it is found; otherwise
NULL is returned.
If
.I c
is '\\0',
.BR index
and
.BR rindex
locate the terminating '\\0'.
.SH SEE ALSO
.BR memchr (3),
.BR strchr (3),
.BR strcspn (3),
.BR strpbrk (3),
.BR strrchr (3),
.BR strsep (3),
.BR strspn (3),
.BR strstr (3),
.BR strtok (3)
.SH HISTORY
Both an
.BR index
and
.BR rindex
function appeared in v6.

38
usr.man/man3/intro.3 Normal file
View File

@ -0,0 +1,38 @@
.\"
.\" Devin Reade, February 1997
.\"
.\" $Id: intro.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH INTRO 3 "2 February 1997" GNO "Library Routines"
.SH NAME
.BR intro
\- introduction to library routines
.SH DESCRIPTION
This chapter provides information on various library routines.
.LP
The
.BR SYNOPSIS
section of each manual page details the prototype of the routine
and any required header files. The
.BR DESCRIPTION
explains the semantics of the routine.
.LP
Reference may be made to symbolic links or other features
or functions that are either unimplemented or otherwise unavailable
under GNO. This information has often been obtained from the original
BSD manual pages. In most cases such information has been retained
in the GNO manual pages either because such functionality is planned
or because the information is relevent to code intended to run on
other BSD operating systems.
.SH RETURN VALUES
In this chapter, return types and values are specific to the particular
routine. The appropriate manual page should be consulted.
.LP
Note that unlike the Chapter 2 calls, routines in this chapter cannot
be relied upon to set
.BR errno (2)
in any predictable way unless doing so is specifically described in
the manual page for that routine.
.SH SEE ALSO
.BR intro (2),
.IR "GNO Kernel Reference Manual" .

90
usr.man/man3/isRootPath.3 Normal file
View File

@ -0,0 +1,90 @@
.\" This man page was written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade.
.\"
.\" $Id: isRootPath.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH ISROOTPATH 3 "30 January 1997" GNO "Library Routines"
.SH NAME
isRootPath - test for a full pathname
.SH SYNOPSIS
#include <gno/gno.h>
int \fBisRootPath\fR (const char *\fIname\fR);
.SH DESCRIPTION
.BR isRootPath
tests the string
.IR name
to see if it is the full specification of a path name to a file starting
at the root of the file system. Under GS/OS,
.IR name
is tested to see if it is a legal volume name, device name, or prefix.
Therefore,
.IR name
is considered to be a full pathname when:
.RS
.sp
It starts with either
.B /
or
.B :
and is at least two characters long;
.sp
It starts with either
.B *
or
.B @
either by themselves or preceeding a
.B /
or
.B :
character;
.sp
It starts with a digit; or
.sp
It starts with
.B .
and is followed by at least one other character, where the next character
is neither
.B /
nor
.BR : .
.RE
.SH RETURN VALUES
1 - \fIname\fR is a full path name.
.br
0 - \fIname\fR is not a full path name.
.SH CAVEATS
Note that no test for existence of the file is made; only the validity
of the file name is checked.
.LP
With GS/OS, unlike the Unix filesystem,
.B /
is not recognised as a complete file (or directory) name. Therefore,
.BR isRootPath
will return 0 if
.BR name
is one character long and isn't
.B *
or
.B @
or a digit.
.LP
Under GS/OS, the test is carried out independant of any mounted file
systems, therefore only GS/OS rules are followed. In particular, there
is no
.BR JudgeName "(3)"
call made, therefore no gaurantee is made that the filename will be valid
for any given file system.
.SH HISTORY
This routine was originally called
.BR if_root_path
and was part of the
.BR lenviron
library. It was adapted from code in
.BR dmake (1)
for GNO v2.0.3 by Devin Reade in April 1994.
It was incorporated into the GNO
.BR libc
as of v2.0.6.
.BR dmake (1)
was written by Dennis Vadura,

38
usr.man/man3/mapErr.3 Normal file
View File

@ -0,0 +1,38 @@
.\" Man page by Devin Reade.
.\"
.\" $Id: mapErr.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH "_MAPERR" 3 "21 January 1997" GNO "Library Routines"
.SH NAME
.BR _mapErr
\- map GS/OS error codes to UNIX errno codes
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int
\fB_mapErr\fR(int \fIerr\fR);
.SH DESCRIPTION
.BR _mapErr
takes a GS/OS error code
.IR err
(typically returned by
.BR toolerror (3)
or taken from the value of the global integer
.BR _toolErr )
and maps it to a UNIX error code suitable for use with
.BR perror (3)
and related routines.
.LP
If
.IR err
is zero,
.BR _mapErr
returns zero.
If there is no direct mapping, then
.BR EIO
is returned.
.SH SEE ALSO
.BR perror (3),
.BR toolerror (3),
and the
.IR "GS/OS Reference Manual" .

162
usr.man/man3/mapMode.3 Normal file
View File

@ -0,0 +1,162 @@
.\" Man page by Devin Reade.
.\"
.\" $Id: mapMode.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH MAPMODE 3 "14 December 1996" GNO "Library Routines"
.SH NAME
.BR _mapMode2GS ,
.BR _mapMode2Unix ,
.BR _getModeEmulation ,
.BR _setModeEmulation
\- (mapMode) perform mappings between Unix and GS/OS file permissions.
.SH SYNOPSIS
#include <sys/types.h>
.br
#include <gno/gno.h>
.sp 1
mode_t
\fB_mapMode2GS\fR (mode_t \fImode\fR);
.br
mode_t
\fB_mapMode2Unix\fR (mode_t \fImode\fR);
.br
int
\fB_getModeEmulation\fR (void);
.br
int
\fB_setModeEmulation\fR (int \fInewval\fR);
.SH DESCRIPTION
These routines are used to do mappings for file access bits between
Unix and GS/OS file systems.
.LP
Under Unix, the lower nine bits of a
.I mode
are broken into groups of three. From most to least significant, these
sets of three bits are used for User, Group, and Other permissions. Within
each set, the bits refer to Read, Write, and Execute permissions.
Under GS/OS, each file has associated with it bits for Read, Write, Invisible,
Backup, Rename, and Destroy.
.LP
By default, the system calls
.BR chmod (2),
.BR creat (2),
and
.BR open (2)
expect their mode parameters to be Unix modes. Before the underlying
GS/OS toolset calls are made, these system calls therefore do mode mapping
via the
.BR _mapMode2GS
call.
(The system calls
.BR fstat (2),
.BR lstat (2),
and
.BR stat (2)
.IR always
return Unix modes in their
.BR st_mode
fields).
.LP
.BR _mapMode2GS
takes a Unix
.I mode
parameter and maps it the GS/OS equivalent.
If the User Read bit is set in
.IR mode ,
the Read bit will be set in the result. If the User Write bit is set in
.IR mode ,
all of the Write, Rename, and Destroy bits will be set in the result.
Regardless of the value of
.IR mode ,
the Invisible bit is always cleared and the Backup bit is always set.
.LP
The reverse mapping may be achieved through
.BR _mapMode2Unix .
This function takes a GS/OS
.I mode
parameter and maps it the Unix equivalent.
If the Read bit in
.IR mode
is set, then the User, Group, and Others Read bits in the result
will be set. If all of the Write, Rename, and Destroy bits are set in
.BR mode ,
then the User, Group and Others Write bits will be set in the result.
(If any of these three are cleared, the Write bits will not be set.)
The result is bitwise
.IR AND ed
with the
.BR umask (2)
before
.BR _mapMode2Unix
returns the value. The high 7 bits (of 16) of the result are always cleared.
.LP
There are times when it may be desirable to disable the mappings done by
.BR _mapMode2Unix
and
.BR _mapMode2GS .
This functionality is achieved through the
.BR _setModeEmulation
function. If
.IR newval
is zero, the mode mapping is turned off; the mapping functions act as
null ops. This implies that the mode parameters of the above system
calls will be interpreted as GS/OS modes, (see the
.BR CreatGS
tool call in the
.IR "GS/OS Reference Manual" ).
.LP
If a non-zero value is given for
.IR newval ,
the mode mapping functions are reactivated.
.LP
.BR _getModeEmulation
allows the application programmer to determine whether or not the
mapping functions are currently active.
.SH COMPATIBILITY
The Orca/C implementations of
.BR chmod (2),
.BR creat (2),
and
.BR open (2)
expect GS/OS
.IR mode
values, which is the opposite of the default for this implementation.
.LP
.BR _getModeEmulation ,
.BR _mapMode2Unix ,
and
.BR _mapMode2GS
are thread safe.
.BR _setModeEmulation
is not.
.SH "RETURN VALUE"
.BR _getModeEmulation
and
.BR _setModeEmulation
return the current or previous emulation value (zero or one), respectively.
.LP
.BR _mapMode2GS
and
.BR _mapMode2Unix
return the appropriately mapped
.IR mode
or, if mapping has been disabled, the original value of
.IR mode .
.SH BUGS
Since these routines don't known anything about file systems, nothing
smart is done for permissions in an AppleShare environment.
.LP
The mappings performed by these routines are by their nature not
entirely reversable.
.SH AUTHOR
Devin Reade <gdr@myrias.com>
.SH "SEE ALSO"
.BR chmod (2),
.BR creat (2),
.BR open (2),
.BR stat (2),
.BR umask (2),
.IR "The Apple IIgs GS/OS Reference" .

90
usr.man/man3/mapPath.3 Normal file
View File

@ -0,0 +1,90 @@
.\" Man page by Devin Reade.
.\"
.\" $Id: mapPath.3,v 1.1 1997/02/27 07:32:23 gdr Exp $
.\"
.TH "MAPPATH" 3 "11 December 1996" GNO "Library Routines"
.SH NAME
.BR _mapPath,
.BR _mapPathGS,
.BR _setPathMapping
\- (mapPath) convert GS/OS paths to Unix-style paths.
.SH SYNOPSIS
.nf
#include <gno/gno.h>
void _setPathMapping (int \fItoggle\fR);
char *_mapPath (char *\fIpathname\fR);
GSStringPtr _mapPathGS (GSStringPtr \fIpathname\fR);
.nf
.SH DESCRIPTION
These routines are intended for use by application programmers who are
porting programs from Unix systems.
.LP
The POSIX 1003.1 standard indicates that the pathname separator (that
character which is used to delimit the components of a pathname) must
be the
.I slash
('/') character. However, GS/OS internally uses the
.I colon
(':') character. This can cause problems with programs that make
assumptions about the pathname separator.
.LP
The routines
.BR _mapPath
and
.BR _mapPathGS ,
if active, map all occurances of the ':' character in
.I pathname
to the '/' character. These routines are intended to be used whenever a
pathname is returned from a GS/OS call. No assumption is made as to the
existance of the file nor the validity of the filename for any given
file system.
.LP
On success, these routines return their original arguments. The only time
.BR _mapPath
or
.BR _mapPathGS
can fail is if mapping is active and
.IR pathname
contains
.I both
the ':' and '/' characters. In such a case, the routine will return NULL and
.IR pathname
will be unchanged.
.LP
For compatibility with native IIgs programs,
.BR _mapPath
and
.BR _mapPathGS
are by default null operations --
.IR pathname
is not modified. In order to activate mapping, the function
.BR _setPathMapping
must be called with a non-zero
.IR toggle .
Although the choice of whether or not to do mapping is usually only
made once in a program, mapping can be turned off again by calling
.BR _setPathMapping
with a zero
.IR toggle .
.LP
These functions are used in various parts of
.BR libc .
Those routines making use of this mapping list the fact in their respective
man pages.
.SH OPTIMIZATION
In cases where it is desirable to avoid the overhead of a function call,
the value of the global integer
.BR __force_slash
may be checked. If it is non-zero, the mapping function should be called:
.nf
if (__force_slash) {
_mapPath(filename);
}
.fi
.SH AUTHOR
Devin Reade <gdr@myrias.com>
.SH "SEE ALSO"
.IR "GS/OS Reference Manual" .

154
usr.man/man3/mktemp.3 Normal file
View File

@ -0,0 +1,154 @@
.\" Copyright (c) 1989, 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.
.\"
.\" @(#)mktemp.3 8.1 (Berkeley) 6/4/93
.\"
.TH MKTEMP 3 "27 January 1997" GNO "Library Routines"
.SH NAME
.BR mktemp
\- make temporary file name (unique)
.SH SYNOPSIS
#include <unistd.h>
.sp 1
char *
\fBmktemp\fR (char *\fItemplate\fR);
.br
int
\fBmkstemp\fR (char *\fItemplate\fR);
.SH DESCRIPTION
The
.BR mktemp
function
takes the given file name template and overwrites a portion of it
to create a file name.
This file name is unique and suitable for use
by the application.
The template may be any file name with some number of
.IR X \'s
appended
to it, for example \fB/tmp/temp.\fIXXXX\fR.
The trailing
.IR X \'s
are replaced with the current process number and/or a
unique letter combination.
The number of unique file names
.BR mktemp
can return depends on the number of
.IR X \'s
provided; six
.IR X \'s
will
result in
.BR mktemp
testing roughly 26 ** 6 combinations.
.LP
The
.BR mkstemp
function
makes the same replacement to the template and creates the template file,
mode 0600, returning a file descriptor opened for reading and writing.
This avoids the race between testing for a file's existence and opening it
for use.
.SH RETURN VALUES
The
.BR mktemp
function
returns a pointer to the template on success and
.BR NULL
on failure.
The
.BR mkstemp
function
returns \-1 if no suitable file could be created.
If either call fails an error code is placed in the global variable
.IR errno .
.SH ERRORS
The
.BR mktemp
and
.BR mkstemp
functions
may set
.IR errno
to one of the following values:
.RS
.IP \fBENOTDIR\fR
The pathname portion of the template is not an existing directory.
.RE
.LP
The
.BR mktemp
and
.BR mkstemp
functions
may also set
.IR errno
to any value specified by the
.BR stat (2)
function.
.LP
The
.BR mkstemp
function
may also set
.IR errno
to any value specified by the
.BR open (2)
function.
.SH NOTES
A common problem that results in a core dump on many architectures
is that the programmer passes in a read-only string to
.BR mktemp
or
.BR mkstemp .
This is common with programs that were developed before
ANSI/C compilers were common.
For example, calling
.BR mkstemp
with an argument of \fB/tmp/tempfile.\fIXXXXXX\fR
will result in a core dump due to
.BR mkstemp
attempting to modify the string constant that was given.
If the program in question makes heavy use of that type
of function call, some compilers have the option of compiling the program
so that it will store string constants in a writable segment of memory
(in the data rather than the text segment). While it is good programming
practise to avoid this problem, it is not strictly necessary under GNO
due to the lack of a write-only text segment.
.SH SEE ALSO
.BR chmod (2),
.BR getpid (2),
.BR open (2),
.BR stat (2)
.SH HISTORY
A
.BR mktemp
function appeared in v7.

25
usr.man/man3/needsgno.3 Normal file
View File

@ -0,0 +1,25 @@
.\"
.\" $Id: needsgno.3,v 1.1 1997/02/27 07:32:24 gdr Exp $
.\"
.TH NEEDSGNO 3 "29 January 1997" GNO "Library Routines"
.SH NAME
.BR needsgno
\- determine if GNO is active
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
int
\fBneedsgno\fR (void);
.SH DESCRIPTION
This function returns 1 if GNO is operating, and zero if it is not.
Use this function to abort programs that use GNO-specific features,
or to allow them to enable non-GNO environment-specific code.
.LP
This call is just a wrapper for the
.BR kernStatus (2)
system call.
.SH SEE ALSO
.BR kernStatus (2),
.BR kernVersion (2),
the
.IR "GNO Kernel Reference Manual" .

81
usr.man/man3/parsearg.3 Normal file
View File

@ -0,0 +1,81 @@
.\"
.\" $Id: parsearg.3,v 1.1 1997/02/27 07:32:24 gdr Exp $
.\"
.TH GNO_COMMAND 3 "27 January 1997" GNO "Library Routines"
.SH NAME
.BR ~GNO_COMMAND ,
.BR ~GNO_PARSEARG ,
.BR ~GNO_FREEARG
\- command line parsing and startup from assembly code
.SH SYNOPSIS
.BR ~GNO_COMMAND
.br
.BR ~GNO_PARSEARG
subroutine (4:\fIcommandline\fR,4:\fIargptr\fR)
.br
.BR ~GNO_FREEARG
subroutine (4:\fIargv\fR,2:\fIargc\fR)
.SH DESCRIPTION
.BR ~GNO_COMMAND
emulates the startup code of a C program, and acts as a wrapper for the
.BR ~GNO_PARSEARG
and
.BR ~GNO_FREEARG
functions, below. To use this routine, immediately execute a JML to
.BR ~GNO_COMMAND
from your first segment. Ensure you have a function
.BR main ()
that conforms to the following C prototype:
.nf
int \fBmain\fR (int \fIargc\fR, char **\fIargv\fR);
.fi
.LP
.BR ~GNO_PARSEARG
will take the command line passed to a utility and parse it into an
.IR argc ,
.IR argv
structure like those used in C programs. This was written
.IR not
as a replacement for a C parser, but for use by assembly language
programmers writing shell commands.
.LP
.IR commandline
is the raw command line string as passed by the calling shell in the
X and Y registers.
.IR argptr
is a pointer to an
.IR argv []-style
array.
.LP
.BR ~GNO_FREEARG
frees the region allocated by
.BR ~GNO_PARSEARG .
.IR argv
and
.IR argc
should be the region pointed to by
.IR argptr
and the return value of
.BR ~GNO_PARSEARG ,
respectively.
.SH RETURN VALUE
.BR ~GNO_COMMAND
returns in the accumulator the value returned by
.BR main ().
.LP
.BR ~GNO_PARSEARG
returns in the accumulator the number of arguments found.
.LP
.BR ~GNO_FREEARG
does not return a value.
.SH HISTORY
These routines first appeared in GNO v1.0. They are based on actual
.BR gsh (1)
parsing code.
.SH CAVEATS
.BR ~GNO_PARSEARG
.IR assumes
that the ByteWorks Memory Manager has been started up and is usable.
No such assumption is made with
.BR ~GNO_COMMAND .

74
usr.man/man3/pause.3 Normal file
View File

@ -0,0 +1,74 @@
.\" 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.
.\"
.\" @(#)pause.3 8.1 (Berkeley) 6/4/93
.\"
.TH PAUSE 3 "29 January 1997" GNO "Library Routines"
.SH NAME
.BR pause
\- suspend a process until a signal arrives.
.SH SYNOPSIS
#include <unistd.h>
.sp 1
int
\fBpause\fR (void);
.SH DESCRIPTION
This function is obsoleted by
.BR sigpause (2).
.LP
The
.BR pause
function
forces a process to pause until any signal arrives.
Upon termination of a signal handler started during a
.BR pause ,
the
.BR pause
call will return.
.SH RETURN VALUES
Always returns \-1.
.SH ERRORS
The
.BR pause
function
always returns:
.RS
.IP \fBEINTR\fR
The call was interrupted.
.RE
.SH SEE ALSO
.BR kill (2),
.BR select (2),
.BR sigpause (2)
.SH HISTORY
A
.BR pause
syscall appeared in v6.

216
usr.man/man3/popen.3 Normal file
View File

@ -0,0 +1,216 @@
.\" Copyright (c) 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.
.\"
.\" @(#)popen.3 8.1 (Berkeley) 6/4/93
.\"
.TH POPEN 3 "23 February 1997" GNO "Library Routines"
.SH NAME
.BR popen ,
.BR pclose
\- process I/O
.SH SYNOPSIS
#include <stdio.h>
.sp 1
FILE *\fBpopen\fR (const char *\fIcommand\fR, const char *\fItype\fR);
.br
int \fBpclose\fR (FILE *\fIstream\fR);
.SH DESCRIPTION
The
.BR popen
function
.IR opens
a process by creating a pipe,
forking,
and invoking the shell.
Since a pipe is by definition unidirectional, the
.I type
argument may specify only reading or writing, not both;
the resulting stream is correspondingly read-only or write-only.
.LP
The
.I command
argument is a pointer to a null-terminated string
containing a shell command line.
This command is passed to
.BR /bin/sh
using the
.BR \-c
flag; interpretation, if any, is performed by the shell.
The
.I mode
argument is a pointer to a null-terminated string
which must be either
.BR r
for reading
or
.BR w
for writing.
.LP
The return value from
.BR popen
is a normal standard I/O stream in all respects
save that it must be closed with
.BR pclose
rather than
.BR fclose .
Writing to such a stream
writes to the standard input of the command;
the command's standard output is the same as that of the process that called
.BR popen ,
unless this is altered by the command itself.
Conversely, reading from a
.IR popened
stream reads the command's standard output, and
the command's standard input is the same as that of the process that called
.BR popen .
.LP
Note that output
.BR popen
streams are fully buffered by default.
.LP
The
.BR pclose
function waits for the associated process to terminate
and returns the exit status of the command
as returned by
.BR waitpid .
.SH RETURN VALUE
The
.BR popen
function returns
.BR NULL
if the
.BR fork (2)
or
.BR pipe (2)
calls fail,
or if it cannot allocate memory.
.LP
The
.BR pclose
function
returns \-1 if
.I stream
is not associated with a
.IR popened
command, if
.I stream
already
.IR pclosed ,
or if
.BR waitpid
returns an error.
.SH ERRORS
The
.BR popen
function does not reliably set
.IR errno .
.SH BUGS
Since the standard input of a command opened for reading
shares its seek offset with the process that called
.BR popen ,
if the original process has done a buffered read,
the command's input position may not be as expected.
Similarly, the output from a command opened for writing
may become intermingled with that of the original process.
The latter can be avoided by calling
.BR fflush (3)
before
.BR popen .
.LP
Failure to execute the shell
is indistinguishable from the shell's failure to execute
.IR command ,
or an immediate exit of the command.
The only hint is an exit status of 127.
.LP
The
.BR popen
argument
always calls
.BR sh (1),
never calls
.BR csh (1).
(Because of a lack of available
.BR sh (1),
the current GNO implementation always calls
.BR gsh (1).)
.LP
This implementation makes use of
.BR waitpid (2).
Because
.BR waitpid
is not currently provided by the GNO kernel,
.BR pclose
is affected by the same bug as is
.BR waitpid ;
other child processes' exit status may be caught (and discarded)
while waiting for the process created by
.BR popen .
Consequently, if the parent processes is doing any other
.BR waitpid
calls (either directly or indirectly),
.BR pclose
may never return.
.LP
Under GNO, the memory region pointed to by
.IR command
must be able to be referenced up to the point that the child process
does its
.BR execl (2).
This implies that if
.IR command
is allocated on the stack and the function which allocated it returns
before the program calls
.BR pclose
(or if the parent exits and makes its child into a zombie), there is a
chance that the forked child of
.BR popen
may try to
.BR execl
an arbitrary command, the results of which are undefined.
.SH SEE ALSO
.BR gsh (1),
.BR sh (1),
.BR fork (2),
.BR pipe (2),
.BR waitpid (2),
.BR fclose (3),
.BR fflush (3),
.BR fopen (3),
.BR stdio (3),
.BR system (3)
.SH HISTORY
A
.BR popen
and a
.BR pclose
function appeared in v7.

22
usr.man/man3/progname.3 Normal file
View File

@ -0,0 +1,22 @@
.\" Man page by Devin Reade.
.\"
.\" $Id: progname.3,v 1.1 1997/02/27 07:32:24 gdr Exp $
.\"
.TH "__PROGNAMEGS" 3 "21 January 1997" GNO "Library Routines"
.SH NAME
.BR __prognameGS
\- get the program name
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
char *\fB__prognameGS\fR (void);
.SH DESCRIPTION
.BR __prognameGS
returns a NULL-terminated string which is the base name of
the executing program. This is a wrapper function to the GS/OS
.BR GetNameGS
system call, and is used in the
.BR err (3)
routines.
.SH SEE ALSO
.BR err (3)

Some files were not shown because too many files have changed in this diff Show More