mirror of https://github.com/GnoConsortium/gno.git
initial checkin of man pages
This commit is contained in:
parent
dde31d4227
commit
a0b2bf9a39
|
@ -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"
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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" .
|
|
@ -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.
|
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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" .
|
|
@ -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.
|
|
@ -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.
|
|
@ -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" .
|
|
@ -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).
|
|
@ -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.
|
|
@ -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).
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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)
|
|
@ -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)
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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"
|
|
@ -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.
|
|
@ -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>
|
||||||
|
|
|
@ -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.
|
|
@ -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).
|
|
@ -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).
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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)
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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).
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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.
|
|
@ -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" .
|
|
@ -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,
|
|
@ -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" .
|
|
@ -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" .
|
|
@ -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" .
|
|
@ -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.
|
|
@ -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" .
|
|
@ -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 .
|
|
@ -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.
|
|
@ -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.
|
|
@ -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
Loading…
Reference in New Issue