diff --git a/usr.man/man1/intro.1 b/usr.man/man1/intro.1 new file mode 100644 index 0000000..841b5e1 --- /dev/null +++ b/usr.man/man1/intro.1 @@ -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" diff --git a/usr.man/man2/accept.2 b/usr.man/man2/accept.2 new file mode 100644 index 0000000..e358641 --- /dev/null +++ b/usr.man/man2/accept.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/access.2 b/usr.man/man2/access.2 new file mode 100644 index 0000000..9bfb429 --- /dev/null +++ b/usr.man/man2/access.2 @@ -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 +.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) diff --git a/usr.man/man2/alarm.2 b/usr.man/man2/alarm.2 new file mode 100644 index 0000000..acfe6b8 --- /dev/null +++ b/usr.man/man2/alarm.2 @@ -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 +.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. diff --git a/usr.man/man2/bind.2 b/usr.man/man2/bind.2 new file mode 100644 index 0000000..654c3e8 --- /dev/null +++ b/usr.man/man2/bind.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/chdir.2 b/usr.man/man2/chdir.2 new file mode 100644 index 0000000..3447193 --- /dev/null +++ b/usr.man/man2/chdir.2 @@ -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 +.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. diff --git a/usr.man/man2/chmod.2 b/usr.man/man2/chmod.2 new file mode 100644 index 0000000..c9f9dba --- /dev/null +++ b/usr.man/man2/chmod.2 @@ -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 +.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 : +.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. diff --git a/usr.man/man2/close.2 b/usr.man/man2/close.2 new file mode 100644 index 0000000..7b93468 --- /dev/null +++ b/usr.man/man2/close.2 @@ -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 +.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). diff --git a/usr.man/man2/connect.2 b/usr.man/man2/connect.2 new file mode 100644 index 0000000..ee8c453 --- /dev/null +++ b/usr.man/man2/connect.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/creat.2 b/usr.man/man2/creat.2 new file mode 100644 index 0000000..ab53c46 --- /dev/null +++ b/usr.man/man2/creat.2 @@ -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 +.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. diff --git a/usr.man/man2/dup.2 b/usr.man/man2/dup.2 new file mode 100644 index 0000000..b6ac615 --- /dev/null +++ b/usr.man/man2/dup.2 @@ -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 +.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). diff --git a/usr.man/man2/execve.2 b/usr.man/man2/execve.2 new file mode 100644 index 0000000..164622e --- /dev/null +++ b/usr.man/man2/execve.2 @@ -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 +.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. diff --git a/usr.man/man2/fork.2 b/usr.man/man2/fork.2 new file mode 100644 index 0000000..dc0b193 --- /dev/null +++ b/usr.man/man2/fork.2 @@ -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 +.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" . diff --git a/usr.man/man2/fork2.2 b/usr.man/man2/fork2.2 deleted file mode 100644 index 0abdc2a..0000000 --- a/usr.man/man2/fork2.2 +++ /dev/null @@ -1,71 +0,0 @@ -.TH FORK2 2 -.SH NAME -fork2 \- start a new process from inside the current application -.SH SYNOPSIS -#include -.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. diff --git a/usr.man/man2/fsync.2 b/usr.man/man2/fsync.2 new file mode 100644 index 0000000..0f4b6fb --- /dev/null +++ b/usr.man/man2/fsync.2 @@ -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 +.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. diff --git a/usr.man/man2/getdtablesize.2 b/usr.man/man2/getdtablesize.2 new file mode 100644 index 0000000..1aa63fa --- /dev/null +++ b/usr.man/man2/getdtablesize.2 @@ -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 +.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. diff --git a/usr.man/man2/getgid.2 b/usr.man/man2/getgid.2 new file mode 100644 index 0000000..e234100 --- /dev/null +++ b/usr.man/man2/getgid.2 @@ -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 +.br +#include +.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). diff --git a/usr.man/man2/getpeername.2 b/usr.man/man2/getpeername.2 new file mode 100644 index 0000000..a8914f8 --- /dev/null +++ b/usr.man/man2/getpeername.2 @@ -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 +.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. diff --git a/usr.man/man2/getpgrp.2 b/usr.man/man2/getpgrp.2 new file mode 100644 index 0000000..d958ce7 --- /dev/null +++ b/usr.man/man2/getpgrp.2 @@ -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 +.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. diff --git a/usr.man/man2/getpid.2 b/usr.man/man2/getpid.2 new file mode 100644 index 0000000..862c9cf --- /dev/null +++ b/usr.man/man2/getpid.2 @@ -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 +.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). diff --git a/usr.man/man2/getsockname.2 b/usr.man/man2/getsockname.2 new file mode 100644 index 0000000..7ffaa41 --- /dev/null +++ b/usr.man/man2/getsockname.2 @@ -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 +.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. diff --git a/usr.man/man2/getsockopt.2 b/usr.man/man2/getsockopt.2 new file mode 100644 index 0000000..6ca8344 --- /dev/null +++ b/usr.man/man2/getsockopt.2 @@ -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 +.br +#include +.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 + +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 , +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 . +.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. diff --git a/usr.man/man2/gettimeofday.2 b/usr.man/man2/gettimeofday.2 new file mode 100644 index 0000000..4ec18c8 --- /dev/null +++ b/usr.man/man2/gettimeofday.2 @@ -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 +.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 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. diff --git a/usr.man/man2/getuid.2 b/usr.man/man2/getuid.2 new file mode 100644 index 0000000..b772727 --- /dev/null +++ b/usr.man/man2/getuid.2 @@ -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 +.br +#include +.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). diff --git a/usr.man/man2/intro.2 b/usr.man/man2/intro.2 new file mode 100644 index 0000000..305b807 --- /dev/null +++ b/usr.man/man2/intro.2 @@ -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 +.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 . 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 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 ). +.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" . diff --git a/usr.man/man2/ioctl.2 b/usr.man/man2/ioctl.2 new file mode 100644 index 0000000..f5501c0 --- /dev/null +++ b/usr.man/man2/ioctl.2 @@ -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 +.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 . +.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. diff --git a/usr.man/man2/jobcontrol.2 b/usr.man/man2/jobcontrol.2 new file mode 100644 index 0000000..aa19ee9 --- /dev/null +++ b/usr.man/man2/jobcontrol.2 @@ -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 +.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 +. 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. diff --git a/usr.man/man2/kernStatus.2 b/usr.man/man2/kernStatus.2 new file mode 100644 index 0000000..0d47217 --- /dev/null +++ b/usr.man/man2/kernStatus.2 @@ -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 +.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 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" . diff --git a/usr.man/man2/kill.2 b/usr.man/man2/kill.2 new file mode 100644 index 0000000..5676309 --- /dev/null +++ b/usr.man/man2/kill.2 @@ -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 +.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). diff --git a/usr.man/man2/listen.2 b/usr.man/man2/listen.2 new file mode 100644 index 0000000..fa79423 --- /dev/null +++ b/usr.man/man2/listen.2 @@ -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 +.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. diff --git a/usr.man/man2/lseek.2 b/usr.man/man2/lseek.2 new file mode 100644 index 0000000..f216aab --- /dev/null +++ b/usr.man/man2/lseek.2 @@ -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 +.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). diff --git a/usr.man/man2/mkdir.2 b/usr.man/man2/mkdir.2 new file mode 100644 index 0000000..a45fd15 --- /dev/null +++ b/usr.man/man2/mkdir.2 @@ -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 + +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). diff --git a/usr.man/man2/open.2 b/usr.man/man2/open.2 new file mode 100644 index 0000000..10deb16 --- /dev/null +++ b/usr.man/man2/open.2 @@ -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 +.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. diff --git a/usr.man/man2/pipe.2 b/usr.man/man2/pipe.2 new file mode 100644 index 0000000..392c167 --- /dev/null +++ b/usr.man/man2/pipe.2 @@ -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 +.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. diff --git a/usr.man/man2/ports.2 b/usr.man/man2/ports.2 new file mode 100644 index 0000000..debf761 --- /dev/null +++ b/usr.man/man2/ports.2 @@ -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 + +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). diff --git a/usr.man/man2/procsend.2 b/usr.man/man2/procsend.2 new file mode 100644 index 0000000..0203ef3 --- /dev/null +++ b/usr.man/man2/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 + +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). \ No newline at end of file diff --git a/usr.man/man2/read.2 b/usr.man/man2/read.2 new file mode 100644 index 0000000..700f52a --- /dev/null +++ b/usr.man/man2/read.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 +.br +#include +.br +#include +.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. diff --git a/usr.man/man2/recv.2 b/usr.man/man2/recv.2 new file mode 100644 index 0000000..6d7d4e1 --- /dev/null +++ b/usr.man/man2/recv.2 @@ -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 +.br +#include +.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 : +.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. diff --git a/usr.man/man2/select.2 b/usr.man/man2/select.2 new file mode 100644 index 0000000..d42d89a --- /dev/null +++ b/usr.man/man2/select.2 @@ -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 +.br +#include +.br +#include +.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. diff --git a/usr.man/man2/semaphore.2 b/usr.man/man2/semaphore.2 new file mode 100644 index 0000000..974da71 --- /dev/null +++ b/usr.man/man2/semaphore.2 @@ -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 +.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. + + diff --git a/usr.man/man2/send.2 b/usr.man/man2/send.2 new file mode 100644 index 0000000..1820e27 --- /dev/null +++ b/usr.man/man2/send.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/setdebug.2 b/usr.man/man2/setdebug.2 new file mode 100644 index 0000000..978d523 --- /dev/null +++ b/usr.man/man2/setdebug.2 @@ -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 +.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 +. +.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: +.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) diff --git a/usr.man/man2/setpgid.2 b/usr.man/man2/setpgid.2 new file mode 100644 index 0000000..5c1b1ff --- /dev/null +++ b/usr.man/man2/setpgid.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 +.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. diff --git a/usr.man/man2/setregid.2 b/usr.man/man2/setregid.2 new file mode 100644 index 0000000..c90c76b --- /dev/null +++ b/usr.man/man2/setregid.2 @@ -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 +.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. diff --git a/usr.man/man2/setreuid.2 b/usr.man/man2/setreuid.2 new file mode 100644 index 0000000..2533850 --- /dev/null +++ b/usr.man/man2/setreuid.2 @@ -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 +.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. diff --git a/usr.man/man2/setruid.2 b/usr.man/man2/setruid.2 new file mode 100644 index 0000000..c5696a3 --- /dev/null +++ b/usr.man/man2/setruid.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/setuid.2 b/usr.man/man2/setuid.2 new file mode 100644 index 0000000..f795ead --- /dev/null +++ b/usr.man/man2/setuid.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/shutdown.2 b/usr.man/man2/shutdown.2 new file mode 100644 index 0000000..d8f44dd --- /dev/null +++ b/usr.man/man2/shutdown.2 @@ -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 +.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. diff --git a/usr.man/man2/sigblock.2 b/usr.man/man2/sigblock.2 new file mode 100644 index 0000000..005ad18 --- /dev/null +++ b/usr.man/man2/sigblock.2 @@ -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 +.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) \ No newline at end of file diff --git a/usr.man/man2/signal.2 b/usr.man/man2/signal.2 new file mode 100644 index 0000000..10ac94c --- /dev/null +++ b/usr.man/man2/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 +.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 : +.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 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. diff --git a/usr.man/man2/sigpause.2 b/usr.man/man2/sigpause.2 new file mode 100644 index 0000000..0400192 --- /dev/null +++ b/usr.man/man2/sigpause.2 @@ -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 +.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) diff --git a/usr.man/man2/sigsetmask.2 b/usr.man/man2/sigsetmask.2 new file mode 100644 index 0000000..33315c1 --- /dev/null +++ b/usr.man/man2/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 +.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) diff --git a/usr.man/man2/socket.2 b/usr.man/man2/socket.2 new file mode 100644 index 0000000..adf93d9 --- /dev/null +++ b/usr.man/man2/socket.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 +.br +#include +.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 +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. diff --git a/usr.man/man2/stat.2 b/usr.man/man2/stat.2 new file mode 100644 index 0000000..314432c --- /dev/null +++ b/usr.man/man2/stat.2 @@ -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 +.br +#include +.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 +(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 , +.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 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. diff --git a/usr.man/man2/statfs.2 b/usr.man/man2/statfs.2 new file mode 100644 index 0000000..8fa1d82 --- /dev/null +++ b/usr.man/man2/statfs.2 @@ -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 +.br +#include +.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. diff --git a/usr.man/man2/times.2 b/usr.man/man2/times.2 new file mode 100644 index 0000000..0b68951 --- /dev/null +++ b/usr.man/man2/times.2 @@ -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 +.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. diff --git a/usr.man/man2/truncate.2 b/usr.man/man2/truncate.2 new file mode 100644 index 0000000..2e54d4b --- /dev/null +++ b/usr.man/man2/truncate.2 @@ -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 +.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. diff --git a/usr.man/man2/umask.2 b/usr.man/man2/umask.2 new file mode 100644 index 0000000..02da2e0 --- /dev/null +++ b/usr.man/man2/umask.2 @@ -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 + +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). diff --git a/usr.man/man2/undocumented.2 b/usr.man/man2/undocumented.2 new file mode 100644 index 0000000..9fc4e76 --- /dev/null +++ b/usr.man/man2/undocumented.2 @@ -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. diff --git a/usr.man/man2/unlink.2 b/usr.man/man2/unlink.2 new file mode 100644 index 0000000..b7a3318 --- /dev/null +++ b/usr.man/man2/unlink.2 @@ -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 +.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. diff --git a/usr.man/man2/utimes.2 b/usr.man/man2/utimes.2 new file mode 100644 index 0000000..02ccda0 --- /dev/null +++ b/usr.man/man2/utimes.2 @@ -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 +.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. diff --git a/usr.man/man2/wait.2 b/usr.man/man2/wait.2 new file mode 100644 index 0000000..4602e56 --- /dev/null +++ b/usr.man/man2/wait.2 @@ -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 +.br +#include +.sp 1 +pid_t +\fBwait\fR (union wait *\fIstatus\fR); +.sp 1 +#include +.br +#include +.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. diff --git a/usr.man/man2/write.2 b/usr.man/man2/write.2 new file mode 100644 index 0000000..2ab6e9e --- /dev/null +++ b/usr.man/man2/write.2 @@ -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 +.br +#include +.br +#include +.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. diff --git a/usr.man/man3/GSString.3 b/usr.man/man3/GSString.3 new file mode 100644 index 0000000..92c5cf7 --- /dev/null +++ b/usr.man/man3/GSString.3 @@ -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 +.br +#include +.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 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 . +.LP +The remaining routines +were reimplemented from spec by Devin Reade . +.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" diff --git a/usr.man/man3/Intro.3 b/usr.man/man3/Intro.3 new file mode 100644 index 0000000..fe5987f --- /dev/null +++ b/usr.man/man3/Intro.3 @@ -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. diff --git a/usr.man/man3/basename.3 b/usr.man/man3/basename.3 new file mode 100644 index 0000000..6b677c5 --- /dev/null +++ b/usr.man/man3/basename.3 @@ -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 +.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 + diff --git a/usr.man/man3/bcopy.3 b/usr.man/man3/bcopy.3 new file mode 100644 index 0000000..568d8be --- /dev/null +++ b/usr.man/man3/bcopy.3 @@ -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 +.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. diff --git a/usr.man/man3/buildCmd.3 b/usr.man/man3/buildCmd.3 new file mode 100644 index 0000000..398d04f --- /dev/null +++ b/usr.man/man3/buildCmd.3 @@ -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 +.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). diff --git a/usr.man/man3/buildEnv.3 b/usr.man/man3/buildEnv.3 new file mode 100644 index 0000000..1332775 --- /dev/null +++ b/usr.man/man3/buildEnv.3 @@ -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 +.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). diff --git a/usr.man/man3/buildPath.3 b/usr.man/man3/buildPath.3 new file mode 100644 index 0000000..4d5115f --- /dev/null +++ b/usr.man/man3/buildPath.3 @@ -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 +.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). diff --git a/usr.man/man3/bzero.3 b/usr.man/man3/bzero.3 new file mode 100644 index 0000000..0235ee0 --- /dev/null +++ b/usr.man/man3/bzero.3 @@ -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 +.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. diff --git a/usr.man/man3/crypt.3 b/usr.man/man3/crypt.3 new file mode 100644 index 0000000..2ecf02b --- /dev/null +++ b/usr.man/man3/crypt.3 @@ -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 +.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. diff --git a/usr.man/man3/directory.3 b/usr.man/man3/directory.3 new file mode 100644 index 0000000..d33d4fa --- /dev/null +++ b/usr.man/man3/directory.3 @@ -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 +#include + +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 : +.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. diff --git a/usr.man/man3/err.3 b/usr.man/man3/err.3 new file mode 100644 index 0000000..74502eb --- /dev/null +++ b/usr.man/man3/err.3 @@ -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 + +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. diff --git a/usr.man/man3/exec.3 b/usr.man/man3/exec.3 new file mode 100644 index 0000000..fdbef88 --- /dev/null +++ b/usr.man/man3/exec.3 @@ -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 +.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). diff --git a/usr.man/man3/execl.3 b/usr.man/man3/execl.3 new file mode 100644 index 0000000..2636d4d --- /dev/null +++ b/usr.man/man3/execl.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 +.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 diff --git a/usr.man/man3/exit.3 b/usr.man/man3/exit.3 new file mode 100644 index 0000000..04625a6 --- /dev/null +++ b/usr.man/man3/exit.3 @@ -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 +.sp 1 +void +\fBexit\fR (int \fIstatus\fR); +.br +void +\fBrexit\fR (int \fIstatus\fR); +.sp 1 +#include +.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. diff --git a/usr.man/man3/fnmatch.3 b/usr.man/man3/fnmatch.3 new file mode 100644 index 0000000..a463c23 --- /dev/null +++ b/usr.man/man3/fnmatch.3 @@ -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 +.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 . +.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) diff --git a/usr.man/man3/fts.3 b/usr.man/man3/fts.3 new file mode 100644 index 0000000..41f3fe6 --- /dev/null +++ b/usr.man/man3/fts.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 +.br +#include +.br +#include +.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 . +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. diff --git a/usr.man/man3/getcwd.3 b/usr.man/man3/getcwd.3 new file mode 100644 index 0000000..5181a01 --- /dev/null +++ b/usr.man/man3/getcwd.3 @@ -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 +.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 ). +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) diff --git a/usr.man/man3/getenv.3 b/usr.man/man3/getenv.3 new file mode 100644 index 0000000..8c1836c --- /dev/null +++ b/usr.man/man3/getenv.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 . 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 +.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. diff --git a/usr.man/man3/getgrent.3 b/usr.man/man3/getgrent.3 new file mode 100644 index 0000000..8e3873e --- /dev/null +++ b/usr.man/man3/getgrent.3 @@ -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 +.br +#include +.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 : +.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. diff --git a/usr.man/man3/gethostname.3 b/usr.man/man3/gethostname.3 new file mode 100644 index 0000000..4138aa6 --- /dev/null +++ b/usr.man/man3/gethostname.3 @@ -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 +.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 +.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). diff --git a/usr.man/man3/getpass.3 b/usr.man/man3/getpass.3 new file mode 100644 index 0000000..f16160f --- /dev/null +++ b/usr.man/man3/getpass.3 @@ -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 +.br +#include +.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. diff --git a/usr.man/man3/getpwent.3 b/usr.man/man3/getpwent.3 new file mode 100644 index 0000000..89d98cc --- /dev/null +++ b/usr.man/man3/getpwent.3 @@ -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 +.br +#include +.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 : +.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. diff --git a/usr.man/man3/getsubopt.3 b/usr.man/man3/getsubopt.3 new file mode 100644 index 0000000..a0e6069 --- /dev/null +++ b/usr.man/man3/getsubopt.3 @@ -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 +.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. diff --git a/usr.man/man3/getttyent.3 b/usr.man/man3/getttyent.3 new file mode 100644 index 0000000..a50490e --- /dev/null +++ b/usr.man/man3/getttyent.3 @@ -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 +.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. diff --git a/usr.man/man3/index.3 b/usr.man/man3/index.3 new file mode 100644 index 0000000..62477b1 --- /dev/null +++ b/usr.man/man3/index.3 @@ -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 +.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. diff --git a/usr.man/man3/intro.3 b/usr.man/man3/intro.3 new file mode 100644 index 0000000..dbf5cfc --- /dev/null +++ b/usr.man/man3/intro.3 @@ -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" . diff --git a/usr.man/man3/isRootPath.3 b/usr.man/man3/isRootPath.3 new file mode 100644 index 0000000..6f99044 --- /dev/null +++ b/usr.man/man3/isRootPath.3 @@ -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 + +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, diff --git a/usr.man/man3/mapErr.3 b/usr.man/man3/mapErr.3 new file mode 100644 index 0000000..fbb493e --- /dev/null +++ b/usr.man/man3/mapErr.3 @@ -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 +.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" . \ No newline at end of file diff --git a/usr.man/man3/mapMode.3 b/usr.man/man3/mapMode.3 new file mode 100644 index 0000000..04a8ae1 --- /dev/null +++ b/usr.man/man3/mapMode.3 @@ -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 +.br +#include +.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 +.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" . \ No newline at end of file diff --git a/usr.man/man3/mapPath.3 b/usr.man/man3/mapPath.3 new file mode 100644 index 0000000..9f3a36d --- /dev/null +++ b/usr.man/man3/mapPath.3 @@ -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 + +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 +.SH "SEE ALSO" +.IR "GS/OS Reference Manual" . diff --git a/usr.man/man3/mktemp.3 b/usr.man/man3/mktemp.3 new file mode 100644 index 0000000..85787b7 --- /dev/null +++ b/usr.man/man3/mktemp.3 @@ -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 +.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. diff --git a/usr.man/man3/needsgno.3 b/usr.man/man3/needsgno.3 new file mode 100644 index 0000000..7069de0 --- /dev/null +++ b/usr.man/man3/needsgno.3 @@ -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 +.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" . diff --git a/usr.man/man3/parsearg.3 b/usr.man/man3/parsearg.3 new file mode 100644 index 0000000..806fb93 --- /dev/null +++ b/usr.man/man3/parsearg.3 @@ -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 . diff --git a/usr.man/man3/pause.3 b/usr.man/man3/pause.3 new file mode 100644 index 0000000..0a342fd --- /dev/null +++ b/usr.man/man3/pause.3 @@ -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 +.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. diff --git a/usr.man/man3/popen.3 b/usr.man/man3/popen.3 new file mode 100644 index 0000000..bb68260 --- /dev/null +++ b/usr.man/man3/popen.3 @@ -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 +.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. diff --git a/usr.man/man3/progname.3 b/usr.man/man3/progname.3 new file mode 100644 index 0000000..545314c --- /dev/null +++ b/usr.man/man3/progname.3 @@ -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 +.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) diff --git a/usr.man/man3/pwcache.3 b/usr.man/man3/pwcache.3 new file mode 100644 index 0000000..4bcdd61 --- /dev/null +++ b/usr.man/man3/pwcache.3 @@ -0,0 +1,89 @@ +.\" 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. +.\" +.\" @(#)pwcache.3 8.1 (Berkeley) 6/9/93 +.\" +.TH PWCACHE 3 "25 February 1997" GNO "Library Routines" +.SH NAME +.BR pwcache +\- cache password and group entries +.SH SYNOPSIS +char *\fBuser_from_uid\fR (uid_t \fIuid\fR, int \fInouser\fR); +.br +char *\fBgroup_from_gid\fR (gid_t \fIgid\fR, int \fInogroup\fR); +.SH DESCRIPTION +.LP +The +.BR user_from_uid +function returns the user name associated with the argument +.IR uid . +The user name is cached so that multiple calls with the same +.I uid +do not require additional calls to +.BR getpwuid (3). +If there is no user associated with the +.IR uid , +a pointer is returned +to a string representation of the +.IR uid , +unless the argument +.I nouser +is non-zero, in which case a +.BR NULL +pointer is returned. +.LP +The +.BR group_from_gid +function returns the group name associated with the argument +.IR gid . +The group name is cached so that multiple calls with the same +.I gid +do not require additional calls to +.BR getgrgid (3). +If there is no group associated with the +.IR gid , +a pointer is returned +to a string representation of the +.IR gid , +unless the argument +.I nogroup +is non-zero, in which case a +.BR NULL +pointer is returned. +.SH SEE ALSO +.BR getgrgid (3), +.BR getpwuid (3) +.SH HISTORY +The +.BR user_from_uid +and +.BR group_from_gid +functions first appeared in 4.4BSD. diff --git a/usr.man/man3/raise.3 b/usr.man/man3/raise.3 new file mode 100644 index 0000000..b14bb12 --- /dev/null +++ b/usr.man/man3/raise.3 @@ -0,0 +1,76 @@ +.\" 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. +.\" +.\" @(#)raise.3 8.1 (Berkeley) 6/4/93 +.\" +.TH RAISE 3 "22 January 1997" GNO "Library Routines" +.SH NAME +.BR raise +\- send a signal to the current process +.SH SYNOPSIS +.br +#include +.sp 1 +int +\fBraise\fR (int \fIsig\fR); +.SH DESCRIPTION +The +.BR raise +function sends the signal +.I sig +to the current process. +.SH RETURN VALUES +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and the global variable +.IR errno +is set to indicate the error. +.SH ERRORS +The +.BR raise +function +may fail and set +.IR errno +for any of the errors specified for the +library functions +.BR getpid (2) +and +.BR kill (2). +.SH SEE ALSO +.BR kill (2) +.SH STANDARDS +The +.BR raise +function +conforms to ANSI/C. diff --git a/usr.man/man3/scandir.3 b/usr.man/man3/scandir.3 new file mode 100644 index 0000000..07564b2 --- /dev/null +++ b/usr.man/man3/scandir.3 @@ -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. +.\" +.\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 +.\" +.TH SCANDIR 3 "27 January 1997" GNO "Library Routines" +.SH NAME +.BR scandir , +.BR alphasort +\- scan a directory +.SH SYNOPSIS +#include +.br +#include +.sp 1 +int +\fBscandir\fR (const char *\fIdirname\fR, +struct dirent ***\fInamelist\fR, +int (*\fIselect\fR) (struct dirent *), +int (*\fIcompar\fR) (const void *, const void *)); +.sp 1 +int +alphasort (const void *d1, const void *d2); +.sp 1 +int +alphacasesort (const void *d1, const void *d2); +.SH DESCRIPTION +The +.BR scandir +function +reads the directory +.I dirname +and builds an array of pointers to directory +entries using +.BR malloc (3). +It returns the number of entries in the array. +A pointer to the array of directory entries is stored in the location +referenced by +.IR namelist . +.LP +The +.I select +parameter is a pointer to a user supplied subroutine which is called by +.BR scandir +to select which entries are to be included in the array. +The select routine is passed a +pointer to a directory entry and should return a non-zero +value if the directory entry is to be included in the array. +If +.I select +is null, then all the directory entries will be included. +.LP +The +.I compar +parameter is a pointer to a user supplied subroutine which is passed to +.BR qsort (3) +to sort the completed array. +If this pointer is null, the array is not sorted. +.LP +The +.BR alphasort +function +is a routine which can be used for the +.I compar +parameter to sort the array alphabetically. +.LP +The +.BR alphacasesort +function is similar to +.BR alphasort , +but can be used for sorting in a case-insensitive manner, and is useful +for the case-insensitive filesystems used by GNO. This function is +specific to GNO. +.LP +The memory allocated for the array can be deallocated with +.BR free (3), +by freeing each pointer in the array and then the array itself. +.SH DIAGNOSTICS +Returns \-1 if the directory cannot be opened for reading or if +.BR malloc (3) +cannot allocate enough memory to hold all the data structures. +.SH SEE ALSO +.BR directory (3), +.BR malloc (3), +.BR qsort (3), +.BR dir (5) +.SH HISTORY +The +.BR scandir +and +.BR alphasort +functions appeared in 4.2BSD. diff --git a/usr.man/man3/setjmp.3 b/usr.man/man3/setjmp.3 new file mode 100644 index 0000000..64de69d --- /dev/null +++ b/usr.man/man3/setjmp.3 @@ -0,0 +1,186 @@ +.\" 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. +.\" +.\" @(#)setjmp.3 8.1 (Berkeley) 6/4/93 +.\" +.TH SETJMP 3 "28 January 1997" GNO "Library Routines" +.SH NAME +.BR sigsetjmp , +.BR siglongjmp , +.BR setjmp , +.BR longjmp , +.BR _setjmp , +.BR _longjmp , +.BR longjmperror +\- non-local jumps +.SH SYNOPSIS +#include +.sp 1 +int +\fBsigsetjmp\fR (sigjmp_buf \fIenv\fR, int \fIsavemask\fR); +.br +void +\fBsiglongjmp\fR (sigjmp_buf \fIenv\fR, int \fIval\fR); +.br +int +\fBsetjmp\fR (jmp_buf \fIenv\fR); +.br +void +\fBlongjmp\fR (jmp_buf \fIenv\fR, int \fIval\fR); +.br +int +\fB_setjmp\fR (jmp_buf \fIenv\fR); +.br +void +\fB_longjmp\fR (jmp_buf \fIenv\fR, int \fIval\fR); +.br +void +\fBlongjmperror\fR (void); +.SH DESCRIPTION +The +.BR sigsetjmp , +.BR setjmp , +and +.BR _setjmp +functions save their calling environment in +.RI ( env ) +Each of these functions returns 0. +.LP +The corresponding +.BR longjmp +functions restore the environment saved by their most recent respective +invocations +of the +.BR setjmp +function. +They then return so that program execution continues as if the corresponding +invocation of the +.BR setjmp +call had just returned the value specified by +.IR val , +instead of 0. +.LP +Pairs of calls may be intermixed, i.e. both +.BR sigsetjmp +and +.BR siglongjmp +and +.BR setjmp +and +.BR longjmp +combinations may be used in the same program, however, individual +calls may not, e.g. the +.I env +argument to +.BR setjmp +may not be passed to +.BR siglongjmp . +.LP +The +.BR longjmp +routines may not be called after the routine which called the +.BR setjmp +routines returns. +.LP +All accessible objects have values as of the time +.BR longjmp +routine was called, except that the values of objects of automatic storage +invocation duration that do not have the +.IR volatile +type and have been changed between the +.BR setjmp +invocation and +.BR longjmp +call are indeterminate. +.LP +The +.BR setjmp / longjmp +pairs save and restore the signal mask while +.BR _setjmp / _longjmp +pairs save and restore only the register set and the stack. +(See +.BR sigprocmask (2).) +.LP +The +.BR sigsetjmp / siglongjmp +function +pairs save and restore the signal mask if the argument +.I savemask +is non-zero, otherwise only the register set and the stack are saved. +.SH ERRORS +If the contents of the +.I env +are corrupted, or correspond to an environment that has already returned, +the +.BR longjmp +routine calls the routine +.BR longjmperror (3). +If +.BR longjmperror +returns the program is aborted (see +.BR abort (3)). +The default version of +.BR longjmperror +prints the message +.I "longjmp botch" +to standard error and returns. +User programs wishing to exit more gracefully should write their own +versions of +.BR longjmperror . +.SH NOTES +The implementation of these routines differs from the Orca/C version, +as does type of +.BR jump_buf +defined in . The two are not compatible and cannot be mixed. +.LP +.BR sigsetjmp +and +.BR siglongjmp +are not currently implemented under GNO. +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR signal (3) +.SH STANDARDS +The +.BR setjmp +and +.BR longjmp +functions conform to ANSI/C. +The +.BR sigsetjmp +and +.BR siglongjmp +functions conform to POSIX 1003.1-88. diff --git a/usr.man/man3/sleep.3 b/usr.man/man3/sleep.3 new file mode 100644 index 0000000..8fd37a0 --- /dev/null +++ b/usr.man/man3/sleep.3 @@ -0,0 +1,69 @@ +.\" Copyright (c) 1986, 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. +.\" +.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93 +.\" +.TH SLEEP 3 "27 January 1997" GNO "Library Routines" +.SH NAME +.BR sleep +\- suspend process execution for interval of seconds +.SH SYNOPSIS +#include +.sp 1 +unsigned int +\fBsleep\fR (unsigned int \fIseconds\fR); +.SH DESCRIPTION +The +.BR sleep +function +suspends execution of the calling process +for +.I seconds +of time. +System activity or time spent in processing the +call may lengthen the sleep by a second. +Because scheduled wakeups occur at fixed 1-second intervals, the +actual suspension time may also be up to 1 second less than requested. +.LP +This function is implemented using +.BR alarm (2) +and +.BR sigpause (2). +.SH RETURN VALUES +This implementation of +.BR sleep +always returns zero. +.SH SEE ALSO +.BR sigpause (2) +.SH HISTORY +A +.BR sleep +function appeared in v7. diff --git a/usr.man/man3/stack.3 b/usr.man/man3/stack.3 new file mode 100644 index 0000000..3c55c6d --- /dev/null +++ b/usr.man/man3/stack.3 @@ -0,0 +1,68 @@ +.\" Man page by Devin Reade. +.\" +.\" $Id: stack.3,v 1.1 1997/02/27 07:32:25 gdr Exp $ +.\" +.TH STACK 3 "11 December 1996" GNO "Library Routines" +.SH NAME +.BR _beginStackCheck , +.BR _endStackCheck +\- report stack usage +.SH SYNOPSIS +.nf +#include + +void _beginStackCheck(void); +int _endStackCheck(void); +.nf +.SH DESCRIPTION +These routines are intended to determine the required stack usage +for a program during the development cycle. +.LP +.BR _beginStackCheck +should be called as soon as possible after the program starts. +.BR _endStackCheck +should be called just prior to program exit. +.BR _endStackCheck +will return the number of bytes of stack space used by the program. The +result can then be used as a +.I lower +bound for the argument to +.BR occ 's +.BR -s +flag, or the +.I stacksize +pragma for Orca/C. +.SH EXAMPLE +An easy way to use these set of routines is to make use of the +.BR atexit (3) +function, so that you don't have to determine all the possible exit +points of your program. +.nf + + #include + #include + + void cleanup (void) { + fprintf(stderr,"Stack Usage: %d bytes\n", _endStackCheck()); + } + + void main (int argc, char **argv) { + + _beginStackCheck(); + atexit(cleanup); + + ... ... + +.fi +.SH AUTHOR +Phillip Vandry +.SH HISTORY +These routines first appeared as stand-along object file, under the names +.BR begin_stack_check +and +.BR end_stack_check . +They were first incorporated into GNO in v2.0.6. +.SH "SEE ALSO" +.BR occ (1), +.BR atexit (1), +Orca/C Reference Manual, Chapter 12. diff --git a/usr.man/man3/strcasecmp.3 b/usr.man/man3/strcasecmp.3 new file mode 100644 index 0000000..e742bb4 --- /dev/null +++ b/usr.man/man3/strcasecmp.3 @@ -0,0 +1,104 @@ +.\" 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. +.\" +.\" @(#)strcasecmp.3 8.1 (Berkeley) 6/9/93 +.\" +.TH STRCASECMP 3 "20 February 1997" GNO "Library Routines" +.SH NAME +.BR strcasecmp , +.BR strncasecmp , +.BR stricmp , +.BR strincmp +\- compare strings, ignoring case +.SH SYNOPSIS +#include +.sp 1 +short +\fBstricmp\fR (const char *\fIs1\fR, const char *\fIs2\fR); +.br +short +\fBstrincmp\fR (const char *\fIs1\fR, const char *\fIs2\fR, unsigned \fIn\fR); +.br +int +\fBstrcasecmp\fR (const char *\fIs1\fR, const char *\fIs2\fR); +.br +int +\fBstrncasecmp\fR (const char *\fIs1\fR, const char *\fIs2\fR, size_t \fIlen\fR); +.SH DESCRIPTION +The +.BR strcasecmp +and +.BR strncasecmp +functions +compare the null-terminated strings +.I s1 +and +.I s2 +and return an integer greater than, equal to, or less than 0, +according as +.I s1 +is lexicographically greater than, equal to, or less than +.I s2 +after translation of each corresponding character to lower-case. +The strings themselves are not modified. +The comparison is done using unsigned characters, so that +.BR \e200 +is greater than +.BR \e0 . +.LP +The +.BR strncasecmp +compares at most +.I len +characters. +.LP +.BR stricmp +and +.BR strincmp +are functionally identically equal to, and implemented in terms of, +.BR strcasecmp +and +.BR strncasecmp , +respectively. +.SH SEE ALSO +.BR bcmp (3), +.BR memcmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strxfrm (3) +.SH HISTORY +The +.BR strcasecmp +and +.BR strncasecmp +functions first appeared in 4.4BSD. diff --git a/usr.man/man3/strdup.3 b/usr.man/man3/strdup.3 new file mode 100644 index 0000000..bbdf2fe --- /dev/null +++ b/usr.man/man3/strdup.3 @@ -0,0 +1,62 @@ +.\" 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. +.\" +.\" @(#)strdup.3 8.1 (Berkeley) 6/9/93 +.\" +.TH STRDUP 3 "27 January 1997" GNO "Library Routines" +.SH NAME +.BR strdup +\- save a copy of a string +.SH SYNOPSIS +#include +.sp 1 +char * +\fBstrdup\fR (const char *\fIstr\fR); +.SH DESCRIPTION +The +.BR strdup +function +allocates sufficient memory for a copy +of the string +.IR str , +does the copy, and returns a pointer to it. +The pointer may subsequently be used as an +argument to the function +.BR free (3). +.LP +If insufficient memory is available, NULL is returned. +.SH SEE ALSO +.BR malloc (3) +.BR free (3) +.SH HISTORY +The +.BR strdup +function first appeared in 4.4BSD. diff --git a/usr.man/man3/strerror.3 b/usr.man/man3/strerror.3 new file mode 100644 index 0000000..0308c4f --- /dev/null +++ b/usr.man/man3/strerror.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 1980, 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. +.\" +.\" @(#)strerror.3 8.1 (Berkeley) 6/9/93 +.\" +.TH STRERROR 3 "June 9, 1993" "BSD 4" "Library Routines" +.SH NAME +.BR perror , +.BR strerror , +.BR sys_errlist , +.BR sys_nerr , +.BR _errnoText +\- system error messages +.SH SYNOPSIS +#include +.sp 1 +void +\fBperror\fR(const char *\fIstring\fR); +.sp 1 +extern const char * const \fBsys_errlist\fR[]; +.br +extern const int \fBsys_nerr\fR; +.sp 1 +#include +.sp 1 +char * +\fBstrerror\fR(int \fIerrnum\fR); +.SH DESCRIPTION +The +.BR strerror +and +.BR perror +functions look up the error message string corresponding to an +error number. +.LP +The +.BR strerror +function accepts an error number argument +.I errnum +and +returns a pointer to the corresponding +message string. +.LP +The +.BR perror +function finds the error message corresponding to the current +value of the global variable +.IR errno +(see +.BR intro (2)) +and writes it, followed by a newline, to the +standard error file descriptor. +If the argument +.I string +is non-NULL, +it is prepended to the message +string and separated from it by +a colon and space. +If +.I string +is +.BR NULL , +only the error message string is printed. +.LP +If +.I errnum +is not a recognized error number, +the error message string will contain +.BR "unknown error:" , +followed by the error number in decimal. +.LP +The message strings can be accessed directly using the external +array +.IR sys_errlist . +The external value +.IR sys_nerr +contains a count of the messages in +.IR sys_errlist . +For backwards compatibility with older versions of GNO, +.BR sys_errlist +can also be referenced through the variable +.BR _errnoText , +which has identical type. +The use of these variables is deprecated; +.BR strerror +should be used instead. +.SH SEE ALSO +.BR intro (2), +.BR psignal (3) +.SH HISTORY +The +.BR strerror +and +.BR perror +functions first appeared in 4.4BSD. +.SH BUGS +For unknown error numbers, the +.BR strerror +function will return its result in a static buffer which +may be overwritten by subsequent calls. +.LP +Programs that use the deprecated +.IR sys_errlist +variable often fail to compile because they declare it +inconsistently. diff --git a/usr.man/man3/strsep.3 b/usr.man/man3/strsep.3 new file mode 100644 index 0000000..bc9734e --- /dev/null +++ b/usr.man/man3/strsep.3 @@ -0,0 +1,106 @@ +.\" 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. +.\" +.\" @(#)strsep.3 8.1 (Berkeley) 6/9/93 +.\" +.TH STRSEP 3 "27 January 1997" GNO "Library Routines" +.SH NAME +.BR strsep +\- separate strings +.SH SYNOPSIS +#include +.sp 1 +char * +\fBstrsep\fR (char **\fIstringp\fR, char *\fIdelim\fR); +.SH DESCRIPTION +The +.BR strsep +function locates, in the string referenced by +.IR *stringp , +the first occurrence of any character in the string +.I delim +(or the terminating +.BR \\0 +character) and replaces it with a +.BR \\0 . +The location of the next character after the delimiter character +(or NULL, if the end of the string was reached) is stored in +.IR *stringp . +The original value of +.I *stringp +is returned. +.LP +An ``empty'' field, i.e. one caused by two adjacent delimiter characters, +can be detected by comparing the location referenced by the pointer returned +in +.I *stringp +to +.BR \\0 . +.LP +If +.I *stringp +is initially +.BR NULL , +.BR strsep +returns +.BR NULL . +.SH EXAMPLES +The following uses +.BR strsep +to parse a string, containing tokens delimited by white space, into an +argument vector: +.nf +char **ap, *argv[10], *inputstring; + +for (ap = argv; (*ap = strsep(&inputstring, " \et")) != NULL;) + if (**ap != '\e0') + ++ap; +.fi +.SH HISTORY +The +.BR strsep +function +is intended as a replacement for the +.BR strtok +function. +While the +.BR strtok +function should be preferred for portability reasons (it conforms to +ANSI/C) +it is unable to handle empty fields, i.e. detect fields delimited by +two adjacent delimiter characters, or to be used for more than a single +string at a time. +The +.BR strsep +function first appeared in 4.4BSD. diff --git a/usr.man/man3/stty.3 b/usr.man/man3/stty.3 new file mode 100644 index 0000000..edc5530 --- /dev/null +++ b/usr.man/man3/stty.3 @@ -0,0 +1,100 @@ +.\" 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. +.\" +.\" @(#)stty.3 8.1 (Berkeley) 6/4/93 +.\" +.TH STTY 3 "29 January 1997" GNO "Library Routines" +.SH NAME +.BR stty , +.BR gtty +\- set and get terminal state (defunct) +.SH SYNOPSIS +#include +.sp 1 +int +\fBstty\fR (int \fIfd\fR, struct sgttyb *\fIbuf\fR); +.br +int +\fBgtty\fR (int \fIfd\fR, struct sgttyb *\fIbuf\fR); +.SH DESCRIPTION +These interfaces are obsoleted by +.BR ioctl (2) +and should be avoided. +.LP +The +.BR stty +function +sets the state of the terminal associated with +.IR fd . +The +.BR gtty +function +retrieves the state of the terminal associated +with +.IR fd . +To set the state of a terminal the call must have +write permission. +.LP +The +.BR stty +call is actually +.nf + + ioctl(fd, TIOCSETP, buf); + +.fi +while the +.BR gtty +call is +.nf + + ioctl(fd, TIOCGETP, buf); + +.fi +See +.BR ioctl (2) +and +.BR tty (4) +for an explanation. +.SH DIAGNOSTICS +If the call is successful 0 is returned, otherwise \-1 is +returned and the global variable +.IR errno +contains the reason for the failure. +.SH SEE ALSO +.BR ioctl (2), +.BR tty (4) +.SH HISTORY +The +.BR stty +and +.BR gtty +functions appeared in 4.2BSD. diff --git a/usr.man/man3/syslog.3 b/usr.man/man3/syslog.3 new file mode 100644 index 0000000..774cc18 --- /dev/null +++ b/usr.man/man3/syslog.3 @@ -0,0 +1,273 @@ +.\" Copyright (c) 1985, 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. +.\" +.\" @(#)syslog.3 8.1 (Berkeley) 6/4/93 +.\" +.TH SYSLOG 3 "28 January 1997" GNO "Library Routines" +.SH NAME +.BR syslog , +.BR vsyslog , +.BR openlog , +.BR closelog , +.BR setlogmask +\- control system log +.SH SYNOPSIS +#include +.br +#include +.sp 1 +void +\fBsyslog\fR (int \fIpriority\fR, const char *\fImessage\fR, ...); +.br +void +\fBvsyslog\fR (int \fIpriority\fR, const char *\fImessage\fR, +va_list \fBargs\fR); +.br +void +\fBopenlog\fR (const char *\fIident\fR, int \fIlogopt\fR, int \fIfacility\fR); +.br +void +\fBcloselog\fR (void); +.br +int +\fBsetlogmask\fR (int \fImaskpri\fR); +.SH DESCRIPTION +The +.BR syslog +function +writes +.I message +to the system message logger. +The message is then written to the system console, log files, +logged-in users, or forwarded to other machines as appropriate. (See +.BR syslogd (8).) +.LP +The message is identical to a +.BR printf (3) +format string, except that +.BR %m +is replaced by the current error +message. (As denoted by the global variable +.IR errno ; +see +.BR strerror (3).) +A trailing newline is added if none is present. +.LP +The +.BR vsyslog +function +is an alternate form in which the arguments have already been captured +using the variable-length argument facilities of +.BR varargs (3). +.LP +The message is tagged with +.IR priority . +Priorities are encoded as a +.I facility +and a +.IR level . +The facility describes the part of the system +generating the message. +The level is selected from the following +.IR ordered +(high to low) list: +.RS +.IP "\fBLOG_EMERG\fR" +A panic condition. +This is normally broadcast to all users. +.IP "\fBLOG_ALERT\fR" +A condition that should be corrected immediately, such as a corrupted +system database. +.IP "\fBLOG_CRIT\fR" +Critical conditions, e.g., hard device errors. +.IP "\fBLOG_ERR\fR" +Errors. +.IP "\fBLOG_WARNING\fR" +Warning messages. +.IP "\fBLOG_NOTICE\fR" +Conditions that are not error conditions, +but should possibly be handled specially. +.IP "\fBLOG_INFO\fR" +Informational messages. +.IP "\fBLOG_DEBUG\fR" +Messages that contain information +normally of use only when debugging a program. +.RE +.LP +The +.BR openlog +function +provides for more specialized processing of the messages sent +by +.BR syslog +and +.BR vsyslog . +The parameter +.I ident +is a string that will be prepended to every message. +The +.I logopt +argument +is a bit field specifying logging options, which is formed by +.BR OR 'ing +one or more of the following values: +.RS +.IP "\fBLOG_CONS\fR" +If +.BR syslog +cannot pass the message to +.BR syslogd (8) +it will attempt to write the message to the console +.BR .ttyco . +.IP "\fBLOG_NDELAY\fR" +Open the connection to +.BR syslogd (8) +immediately. +Normally the open is delayed until the first message is logged. +Useful for programs that need to manage the order in which file +descriptors are allocated. +.IP "\fBLOG_PERROR\fR" +Write the message to standard error output as well to the system log. +.IP "\fBLOG_PID\fR" +Log the process id with each message: useful for identifying +instantiations of daemons. +.RE +.LP +The +.I facility +parameter encodes a default facility to be assigned to all messages +that do not have an explicit facility encoded: +.RS +.IP "\fBLOG_AUTH\fR" +The authorization system: +.BR login (1), +.BR su (1), +.BR getty (8), +etc. +.IP "\fBLOG_AUTHPRIV\fR" +The same as +.BR LOG_AUTH , +but logged to a file readable only by +selected individuals. +.IP "\fBLOG_CRON\fR" +The cron daemon: +.BR cron (8). +.IP "\fBLOG_DAEMON\fR" +System daemons, such as +.BR routed (8), +that are not provided for explicitly by other facilities. +.IP "\fBLOG_FTP\fR" +The file transfer protocol daemon: +.BR ftpd (8). +.IP "\fBLOG_KERN\fR" +Messages generated by the kernel. +These cannot be generated by any user processes. +.IP "\fBLOG_LPR\fR" +The line printer spooling system: +.BR lpr (1), +.BR lpc (8), +.BR lpd (8), +etc. +.IP "\fBLOG_MAIL\fR" +The mail system. +.IP "\fBLOG_NEWS\fR" +The network news system. +.IP "\fBLOG_SYSLOG\fR" +Messages generated internally by +.BR syslogd (8). +.IP "\fBLOG_USER\fR" +Messages generated by random user processes. +This is the default facility identifier if none is specified. +.IP "\fBLOG_UUCP\fR" +The uucp system. +.IP "\fBLOG_LOCAL0\fR" +Reserved for local use. +Similarly for +.BR LOG_LOCAL1 +through +.BR LOG_LOCAL7 . +.RE +.LP +The +.BR closelog +function +can be used to close the log file. +.LP +The +.BR setlogmask +function +sets the log priority mask to +.I maskpri +and returns the previous mask. +Calls to +.BR syslog +with a priority not set in +.I maskpri +are rejected. +The mask for an individual priority +.I pri +is calculated by the macro +.BR LOG_MASK pri ; +the mask for all priorities up to and including +.I toppri +is given by the macro +.BR LOG_UPTO toppri ; . +The default allows all priorities to be logged. +.SH RETURN VALUES +The routines +.BR closelog , +.BR openlog , +.BR syslog +and +.BR vsyslog +return no value. +.LP +The routine +.BR setlogmask +always returns the previous log mask level. +.SH EXAMPLES +.nf +syslog(LOG_ALERT, "who: internal error 23"); + +openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); + +setlogmask(LOG_UPTO(LOG_ERR)); + +syslog(LOG_INFO, "Connection from host %d", CallingHost); + +syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); +.fi +.SH SEE ALSO +.BR logger (1), +.BR syslogd (8) +.SH HISTORY +These +functions appeared in 4.2BSD. diff --git a/usr.man/man3/tmpnam.3 b/usr.man/man3/tmpnam.3 new file mode 100644 index 0000000..697b17a --- /dev/null +++ b/usr.man/man3/tmpnam.3 @@ -0,0 +1,210 @@ +.\" 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: @(#)tmpnam.3 5.14 (Berkeley) 6/29/91 +.\" tmpnam.3,v 1.2 1993/08/01 07:44:48 mycroft Exp +.\" +.TH TMPFILE 3 "26 November 1995" GNO "Library Routines" +.SH NAME +.BR tempnam , +.BR tmpfile , +.BR tmpnam +\- temporary file routines +.SH SYNOPSIS +#include +.sp 1 +FILE * +\fBtmpfile\fR(void); +.br +char * +\fBtmpnam\fR(char *\fIstr\fR); +.br +char * +\fBtempnam\fR(const char *\fItmpdir\fR, const char *\fIprefix\fR); +.SH DESCRIPTION +The +.B tmpfile +function +returns a pointer to a stream associated with a file descriptor returned +by the routine +.BR mkstemp (3). +The created file is unlinked before +.B tmpfile +returns, causing the file to be automatically deleted when the last +reference to it is closed. +The file is opened with the access value +.BR w+b . +.LP +The +.B tmpnam +function +returns a pointer to a file name, in the +.B P_tmpdir +directory, which +did not reference an existing file at some indeterminate point in the +past. +.B P_tmpdir +is defined in the include file +.BR stdio.h . +If the argument +.I str +is non-NULL, +the file name is copied to the buffer it references. +Otherwise, the file name is copied to a static buffer. +In either case, +.B tmpnam +returns a pointer to the file name. +.LP +The buffer referenced by +.I str +is expected to be at least +.B L_tmpnam +bytes in length. +.B L_tmpnam +is defined in the include file +.BR stdio.h . +.LP +The +.B tempnam +function +is similar to +.BR tmpnam , +but provides the ability to specify the directory which will +contain the temporary file and the file name prefix. +.LP +The environment variable +.B TMPDIR +(if set), the argument +.I dir +(if non-NULL), the directory +.BR P_tmpdir , +and the directory +.B /tmp +are tried, in the listed order, as directories in which to store the +temporary file. +.LP +The argument +.IR prefix , +if non-NULL, +is used to specify a file name prefix, which will be the +first part of the created file name. +.B Tempnam +allocates memory in which to store the file name; the returned pointer +may be used as a subsequent argument to +.BR free (3). +.SH RETURN VALUES +The +.B tmpfile +function +returns a pointer to an open file stream on success, and a +NULL pointer on error. +.LP +The +.B tmpnam +and +.B tempfile +functions +return a pointer to a file name on success, and a +NULL pointer on error. +.SH ERRORS +The +.B tmpfile +function +may fail and set the global variable +.B errno +for any of the errors specified for the library functions +.BR fdopen (3) +or +.BR mkstemp (3). +.LP +The +.B tmpnam +function +may fail and set +.B errno +for any of the errors specified for the library function +.BR mktemp (3). +.LP +The +.B tempnam +function +may fail and set +.B errno +for any of the errors specified for the library functions +.BR malloc (3) +or +.B mktemp (3). +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3) +.SH STANDARDS +The +.B tmpfile +and +.B tmpnam +functions conform to ANSI C. +.SH BUGS +These interfaces are provided for System V and ANSI +compatibility only. +The +.BR mkstemp (3) +interface is strongly preferred. +.LP +There are four important problems with these interfaces (as well as +with the historic +.BR mktemp (3) +interface). +First, there is an obvious race between file name selection and file +creation and deletion. +Second, most historic implementations provide only a limited number +of possible temporary file names (usually 26) before file names will +start being recycled. +Third, the System V implementations of these functions (and of +.BR mktemp ) +use the +.BR access (2) +function to determine whether or not the temporary file may be created. +This has obvious ramifications for setuid or setgid programs, complicating +the portable use of these interfaces in such programs. +Finally, there is no specification of the permissions with which the +temporary files are created. +.LP +This implementation does not have these flaws, but portable software +cannot depend on that. +In particular, the +.BR tmpfile +interface should not be used in software expected to be used on other systems +if there is any possibility that the user does not wish the temporary file to +be publicly readable and writable. diff --git a/usr.man/man3/ttyname.3 b/usr.man/man3/ttyname.3 new file mode 100644 index 0000000..fcf3924 --- /dev/null +++ b/usr.man/man3/ttyname.3 @@ -0,0 +1,122 @@ +.\" 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. +.\" +.\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93 +.\" +.TH TTYNAME 3 "29 January 1997" GNO "Library Routines" +.SH NAME +.BR ttyname , +.BR isatty , +.BR ttyslot +\- get name of associated terminal (tty) from file descriptor +.SH SYNOPSIS +#include +.sp 1 +char * +\fBttyname\fR (int \fIfd\fR); +.br +int +\fBisatty\fR (int \fIfd\fR); +.br +int +\fBttyslot\fR (void); +.SH DESCRIPTION +These functions operate on the system file descriptors for terminal +type devices. These descriptors are not related to the standard I/O +.BR FILE +typedef, but refer to the special device named \fB.tty\fIxx\fR +and for which an entry exists +in the initialization file +.BR /etc/ttys . +(See +.BR ttys (5).) +.LP +The +.BR isatty +function +determines if the file descriptor +.I fd +refers to a valid +terminal type device. +.LP +The +.BR ttyname +function +gets the related device name of +a file descriptor for which +.BR isatty +is true +.LP +The +.BR ttyslot +function +fetches the current process' control terminal number from the +.BR ttys (5) +file entry. +.SH RETURN VALUES +The +.BR ttyname +function +returns the null terminated name if the device is found and +.BR isatty +is true; otherwise +a +.BR NULL +pointer is returned. +.LP +The +.BR ttyslot +function +returns the unit number of the device file if found; otherwise +the value zero is returned. +.SH FILES +.RS +.It Pa /dev/\(** +.It Pa /etc/ttys +.RE +.SH SEE ALSO +.BR ioctl (2), +.BR ttys (5) +.SH HISTORY +A +.BR isatty , +.BR ttyname , +and +.BR ttyslot +function +appeared in v7. +.SH BUGS +The +.BR ttyname +function leaves its result in an internal static object and returns +a pointer to that object. Subsequent calls to +.BR ttyname +will modify the same object. diff --git a/usr.man/man3/utime.3 b/usr.man/man3/utime.3 new file mode 100644 index 0000000..01f3179 --- /dev/null +++ b/usr.man/man3/utime.3 @@ -0,0 +1,85 @@ +.\" 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. +.\" +.\" @(#)utime.3 8.1 (Berkeley) 6/4/93 +.\" +.TH UTIME 3 "6 January 1997" GNO "Library Routines" +.SH NAME +.BR utime +\- set file times +.SH SYNOPSIS +#include +.br +#include +.sp 1 +int +\fButime\fR (const char *\fIfile\fR, const struct utimbuf *\fItimep\fR); +.SH DESCRIPTION +The +.BR utime +function sets the access and modification times of the named file from +the structures in the argument array +.IR timep . +.LP +If the times are specified (the +.I timep +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 timep +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 ERRORS +The +.BR utime +function may fail and set +.IR errno +for any of the errors specified for the library function +.BR utimes (2). +.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 utimes (2) +.SH HISTORY +A +.BR utime +function appeared in v7. +.SH STANDARDS +With the exception of the items listed under +.BR BUGS , +the +.BR utime +function conforms to +POSIX 1003.1-88. diff --git a/usr.man/man4/intro.4 b/usr.man/man4/intro.4 new file mode 100644 index 0000000..12aee1f --- /dev/null +++ b/usr.man/man4/intro.4 @@ -0,0 +1,21 @@ +.\" +.\" Devin Reade, January 1997 +.\" +.\" $Id: intro.4,v 1.1 1997/02/27 07:32:28 gdr Exp $ +.\" +.TH INTRO 4 "12 January 1997" GNO Devices +.SH NAME +intro \- introduction to device drivers +.SH DESCRIPTION +This chapter describes GNO device drivers. +.LP +Note that device drivers under GNO are referenced by the GS/OS convention +of using a preceeding dot (such as +.BR .tty ). +This differs from other Unix implementations that use device files in the +.BR /dev +directory. +.SH SEE ALSO +.IR "GNO Kernel Reference Manual" , +.br +.IR "GNO Shell (gsh) Reference Manual" . diff --git a/usr.man/man4/tty.4 b/usr.man/man4/tty.4 new file mode 100644 index 0000000..b8d00ac --- /dev/null +++ b/usr.man/man4/tty.4 @@ -0,0 +1,274 @@ +.\" +.\" Devin Reade, January 1997 +.\" +.\" $Id: tty.4,v 1.1 1997/02/27 07:32:28 gdr Exp $ +.\" +.TH TTY 4 "27 January 1997" GNO Devices +.SH NAME +.BR tty +\- general terminal interface +.SH SYNOPSIS +#include +.SH DESCRIPTION +This file documents the special file +.BR .tty +and the terminal drivers used for user-oriented I/O. +.IP "\fBThe Controlling Terminal\fR" +Every process has associated with it a controlling terminal, which is +the terminal from which the process was invoked. In some versions of +Unix, the controlling terminal association is responsible for job +control; this is not so under GNO. A process' controlling terminal is +inherited from its parent. By opening the special file +.BR .tty , +a process can access its controlling terminal. This is useful where the +input and output of a process was redirected and the process wants to +be sure of getting input from or output to the user at the terminal. +.sp 1 +A process can remove the association it has with its controlling terminal +by opening the file +.BR .tty +and issuing the system call +.RS +.sp 1 +ioctl (\fIfd\fR, TIOCNOTTY, 0); +.sp 1 +.RE +where +.IR fd +is the file descriptor associated with +.BR .tty . +This is often desirable in server processes. +.IP "\fBProcess Groups\fR" +Every terminal has an associated process group. Any time a +signal-generating special character is typed at the terminal, the +terminal's process group is sent that signal. Unix systems set process +groups using +.BR ioctl (2) +calls, but under GNO a new interface method is used; +process group assignments are controlled with the +.BR JOBCONTROL (2) +routines. +.IP \fBModes\fR +There are four modes in which terminal drivers operate. These modes +control how the driver deals with I/O. +.RS +.IP \fIcooked\fR +This is the default mode of the terminal driver. If an incoming +character is one of the special characters defined in +.BR sgttyb , +.BR tchars , +or +.BR ltchars , +the appropriate action is performed (see below). On Unix systems, +this mode also allows for input editing. It is called +.IR cooked +mode and is the normal state of the terminal driver. Due to the history +of the Apple II and it's operating systems, this precedent was not followed. +Instead, to get input editing features, use the ReadLine Toolbox call. +Cooked-mode input editing may be implemented for future releases of GNO. +.sp 1 +.I "GDR: This is a deviation from the GNO v2.0.4 man page ..." +.IP \fInewline\fR + + +This mode is selected by using the GS/OS NewLine call. Input is collected until one of the newline characters specified in the NewLine call is encountered. At that point, the line of input is returned, even if less than the number of bytes requested in the Read call are read. I/O processing features are enabled and disabled independently of newline mode; see cooked, cbreak, and raw. + +cbreak With GNO/ME, this mode is the default state of the terminal driver, and is synonymous with cooked mode. The requested number of characters are read without regard to any newline setting; input is not line buffered before being returned to the process. + +raw No input or output processing is performed, and the driver does not check for any special characters. + + +Summary of terminal control modes + +Due to the colorful history of Unix systems, the data structures used to manipulate terminal modes and settings are separated into four groups. Future revisions of GNO may implement the SunOS termio interface, which consolidate these structures into one place. + +sgtty +The basic ioctls use the structure defined in : + +struct sgttyb { + char sg_ispeed; + char sg_ospeed; + char sg_erase; + char sg_kill; + short sg_flags; +}; + +sg_ispeed and sg_ospeed indicate the baud rates for input and output according to the following table. Speed changes that do not apply to a particular piece of hardware are ignored (for instance, the console driver does not access a serial port so all baud rate settings are, in effect, impossible). Also, not all the baud rates supported by a particular device are allowed to be set from this interface. + +These symbolic names for the baud rate settings are defined in . + +B0 0 (hang up dataphone) +B50 1 50 baud +B75 2 75 baud +B110 3 110 baud +B134 4 134.5 baud +B150 5 150 baud +B200 6 200 baud +B300 7 300 baud +B600 8 600 baud +B1200 9 1200 baud +B1800 10 1800 baud +B2400 11 2400 baud +B4800 12 4800 baud +B9600 13 9600 baud +B19200 and +EXTA 14 19200 baud +B38400 and +EXTB 15 38400 baud + +The sg_erase and sg_kill fields specify the line-editing erase and kill characters; these are not currently used. + +sg_flags is a bitmapped value that indicates various state settings for the terminal driver (values are in hex). + +RAW 0000020 Raw mode: wake up on all characters, 8-bit interface +CRMOD 0000010 Map CR into LF; output LF as CR-LF +ECHO 0000008 Echo (full duplex) +CBREAK 0000002 Return each character as soon as typed +TANDEM 0000001 Automatic flow control + +RAW and CBREAK modes were described above, in Modes. + +If the CRMOD bit is set, a line feed character is appended to any echoed or ouputted carriage return. + +The ECHO bit controls input echoing; if enabled, any characters read from the terminal are echoed. This behavior differs slightly from Unix, where input characters are echoed as soon as typed. + +TANDEM mode enables automatic software flow control utilizing the special characters t_startc and t_stopc in tchars (below). Whenever the input queue is in danger of overflowing, the system sends t_stopc; when the queue has drained sufficiently, t_startc is sent. This mode has no effect on the console driver. + +Note: t_startc and t_stopc are used for both directions of flow control; when t_stopc is received from a remote system (or user), the terminal stops output, and when t_startc is received output resumes. Certain drivers may also require t_stopc and t_startc to be the same character, in which case one or the other setting will be ignored. See the driver's documentation for details. + + +Basic Ioctls + +Most ioctl() calls apply to terminals. They have the form +#include + +ioctl(int filedes, unsigned long code, void *arg) + +arg is usually a pointer to a structure or int. The ioctl codes that apply to sgtty are: + +TIOCGETP Fetch the basic parameters associated with the terminal, and store in the sgttyb structure pointed to by arg. + +TIOCSETP Set the terminal's basic parameters according to the sgttyb structure pointed to by arg. The input queue is flushed, and the call waits for the output queue to drain before the parameters are changed. + +TIOCSETN This is like TIOCSETP, except there is no delay and the input queue is not flushed. + +With the following codes arg is ignored. + +TIOCEXCL Set "exclusive-use" mode. The terminal may not be opened again by any process until all existing references are closed. + +TIOCNXCL Turns off "exclusive-use" mode. + +TIOCHPCL When the last reference to the terminal is closed, the terminal line is forced to hang up. This applies only to modem drivers. + +With the following codes, arg is a pointer to an int. + +TIOCGETD The current line discipline number is stored in the int pointed to by arg. This value is currently ignored. + +TIOCSETD The line discipline is set according to the int pointed to by arg. + + + +TIOCFLUSH The specified queue is flushed. If the value pointed to by arg is zero, both the input and output queues are flushed. If the value is FREAD (defined in ), the input queue is flushed. If the value is FWRITE, the output queue is flushed. + +The last few calls permit detailed control of the driver. In cases where an argument is required, it is described. Otherwise, arg should be a NULL pointer. + +TIOCSTI The character pointed to by the argument is placed in the input queue as if it had been typed on the terminal. + +TIOCSBRK Begins a break sequence on the terminal. + +TIOCCBRK Ends a break sequence. + +TIOCSDTR The DTR line is turned on + +TIOCCDTR The DTR line is turned off + +TIOCSTOP Output is stopped as if t_stopc had been typed on the terminal. + +TIOCSTART If output is stopped, it is resumed as if t_startc had been typed on the terminal. + +TIOCOUTQ The number of characters in the output queue is returned in the int pointed to by arg. + +FIONREAD The number of characters immediately available for input from the terminal is returned in the int pointed to by arg. This is the preferred method of non-blocking I/O (checking for the presence of characters without waiting for them). + + +Tchars +The second structure associated with a terminal defines special characters. The structure is defined in which is automatically included by . + +struct tchars { + char t_intrc; /* interrupt */ + char t_quitc; /* quit */ + char t_startc; /* start output */ + char t_stopc; /* stop output */ + char t_eofc; /* end-of-file */ + char t_brkc; /* input delimiter (like nl) */ +}; + +The default values for these characters are ^C, ^\, ^Q, ^S, ^D and -1 respectively. A value of -1 for any of the characters means that the effect of that character is ignored. The stop and start characters may be the same to produce a 'toggle' effect. It is not recommended to set any of the other characters to the same values; the order in which the special characters are checked is not defined, and the results you get may not be what was expected. +The ioctl calls that apply to tchars are: + +TIOCGETC Returns the special characters settings in the tchars structure pointed to by arg. + +TIOCSETC The special characters are set according to the given structure. + +Local mode + +The third structure in the terminal interface is a local mode word. None of the options are currently implemented for the console driver. Other drivers may implement them; see the appropriate manpages for details. + +The ioctl's used to access the local mode follow. arg in all cases is a pointer to an int. + +TIOCLBIS The bits of the local mode word specified by `1' bits in the argument are set; this operation is a bit-wise OR. + +TIOCLBIC The bits of the local mode word specified by `1' bits in the argument are cleared; this operation ANDs the local mode with the bitwise negation of the argument. + +TIOCLSET Sets the local mode word to the value of the argument. + +TIOCLGET Returns the local mode word in the int pointed to by arg. + + +Local Special Characters +The fourth terminal structure is another set of special characters. The structure is named ltchars and is again defined in . + +struct ltchars { + char t_suspc; /* stop process signal */ + char t_dsuspc; /* delayed stop process signal */ + char t_rprntc; /* reprint line */ + char t_flushc; /* flush output (toggles) */ + char t_werasc; /* word erase */ + char t_lnextc; /* literal next character */ +}; + +Defaults for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V. As with tchars, a value of -1 disables the effect of that character. Only t_suspc is currently implemented for the console driver. + +The applicable ioctl functions are: + +TIOCSLTC sets the local characters according to the ltchars structure pointed to by arg. + +TIOCGLTC retreives the local characters, storing them in the argument. + + +Window/terminal sizes + +Provision is made for storage of the current window or terminal size along with the other terminal information. This info is recorded in a winsize structure, and is defined in : + +struct winsize { + unsigned short ws_row; /* rows, in characters */ + unsigned short ws_col; /* columns, in characters */ + unsigned short ws_xpixel; /* horizontal size, pixels */ + unsigned short ws_ypixel; /* vertical size, pixels */ +}; + +A '0' in a field indicates that the field value is undefined. '0' is the default when a terminal is first opened. These values are not used by the terminal driver itself; rather, they are for the benefit of applications. The ioctl calls for winsize are: + +TIOCGWINSZ + Returns the window size parameters in the provided winsize structure. + +TIOCSWINSZ + Sets the window size parameters. If any of the values differ from the old ones, a SIGWINCH signal is sent to the terminal's process group. + +FILES +.tty +.ttyco (console driver) +.tty* (user-installed drivers) + +SEE ALSO +GNO Shell Reference Manual, stty(1), ioctl(2), signal(2) \ No newline at end of file diff --git a/usr.man/man5/intro.5 b/usr.man/man5/intro.5 new file mode 100644 index 0000000..253369c --- /dev/null +++ b/usr.man/man5/intro.5 @@ -0,0 +1,31 @@ +.\" +.\" Devin Reade, February 1997 +.\" +.\" $Id: intro.5,v 1.1 1997/02/27 07:32:29 gdr Exp $ +.\" +.TH INTRO 5 "2 February 1997" GNO "File Formats" +.SH NAME +intro \- introduction to file formats +.SH DESCRIPTION +This chapter describes the format of various special files used by +GNO. Many of these will be text files that can be modified for +specific site configurations. Others will describe file types that +cannot be modified with impunity. +.LP +Most standard IIgs file types do not have manual pages written for +them. Instead, the base documents listed in the +.BR "SEE ALSO" +section should be consulted. +.SH SEE ALSO +.IR "Apple IIgs GS/OS Reference" , +.br +.IR "Inside Macintosh: Files" , +.br +.IR "Orca/M Reference Manual" , +.br +.IR "Programmer's Reference Manual for System 6.0/6.0.1" , +.br +Apple DTS (Developer Technical Support) +.IR "Technical Notes" +and +.IR "File Type Notes" . diff --git a/usr.man/man6/intro.6 b/usr.man/man6/intro.6 new file mode 100644 index 0000000..8f1c426 --- /dev/null +++ b/usr.man/man6/intro.6 @@ -0,0 +1,28 @@ +.\" +.\" Devin Reade, February 1997 +.\" +.\" $Id: intro.6,v 1.1 1997/02/27 07:32:29 gdr Exp $ +.\" +.TH INTRO 6 "2 February 1997" GNO "Games" +.SH NAME +intro \- introduction to games +.SH DESCRIPTION +This chapter describes games. Traditionally, these have been kept +separate from user programs. GNO follows this convention. +.LP +Games are normally kept in the directory +.BR /usr/games . +Those that require configuration files should have such files in +.BR /usr/games/lib . +The directories +.BR /usr/lib +and +.BR /usr/local/lib +have also been used on occasion, but this is discouraged. +.LP +The manual page syntax of this chapter conforms to that of Chapter 1, +.IR "Commands and Applications" . +.LP +Most games described in this chapter will be text-oriented. +.SH SEE ALSO +.BR intro (1) diff --git a/usr.man/man7/intro.7 b/usr.man/man7/intro.7 new file mode 100644 index 0000000..6cbfb4d --- /dev/null +++ b/usr.man/man7/intro.7 @@ -0,0 +1,11 @@ +.\" +.\" Devin Reade, February 1997 +.\" +.\" $Id: intro.7,v 1.1 1997/02/27 07:32:30 gdr Exp $ +.\" +.TH INTRO 7 "2 February 1997" GNO "Miscellaneous" +.SH NAME +intro \- introduction to miscellaneous information +.SH DESCRIPTION +This chapter contains manual pages which do not fit into any of the +other chapters' categories. diff --git a/usr.man/man8/intro.8 b/usr.man/man8/intro.8 new file mode 100644 index 0000000..49863ea --- /dev/null +++ b/usr.man/man8/intro.8 @@ -0,0 +1,28 @@ +.\" +.\" Devin Reade, February 1997 +.\" +.\" $Id: intro.8,v 1.1 1997/02/27 07:32:31 gdr Exp $ +.\" +.TH INTRO 8 "2 February 1997" GNO "System Administration" +.SH NAME +intro \- introduction to system administration +.SH DESCRIPTION +The commands described in this chapter are intended only for system +administration tasks. On traditional Unix systems, use of these +routines are typically restricted to the superuser (root). +.LP +System administration commands are usually kept in either +.BR /sbin , +.BR /usr/sbin , +or +.BR /etc . +Because of the lack of user file permissions under GNO, it is often +possible for non-privaledged users to execute these commands. Therefore, +in the interest of system integrity, these directories should not be in the +.BR PATH +of any user other than the superuser. +.LP +The manual page syntax of this chapter conforms to that of Chapter 1, +.IR "Commands and Applications" . +.SH SEE ALSO +.BR intro (1) diff --git a/usr.man/mkso.data b/usr.man/mkso.data new file mode 100644 index 0000000..1d9e4bd --- /dev/null +++ b/usr.man/mkso.data @@ -0,0 +1,154 @@ +# +# The first column is the "real" man page; the second is the .so link. +# +# $Id: mkso.data,v 1.1 1997/02/27 07:31:17 gdr Exp $ +# +man2/alarm.2 man2/alarm10.2 +man2/chmod.2 man2/fchmod.2 +man2/dup.2 man2/dup2.2 +man2/execl.2 man2/execle.2 +man2/execl.2 man2/execlp.2 +man2/execl.2 man2/execv.2 +man2/execl.2 man2/execvp.2 +man2/execve.2 man2/_execve.2 +man2/fork.2 man2/fork2.2 +man2/fork.2 man2/vfork.2 +man2/getgid.2 man2/getegid.2 +man2/getpgrp.2 man2/_getpgrp.2 +man2/getpid.2 man2/getppid.2 +man2/getsockopt.2 man2/setsockopt.2 +man2/gettimeofday.2 man2/settimeofday.2 +man2/getuid.2 man2/geteuid.2 +man2/jobcontrol.2 man2/settpgrp.2 +man2/jobcontrol.2 man2/tcnewpgrp.2 +man2/jobcontrol.2 man2/tctpgrp.2 +man2/kernStatus.2 man2/kernVersion.2 +man2/ports.2 man2/pbind.2 +man2/ports.2 man2/pcreate.2 +man2/ports.2 man2/pdelete.2 +man2/ports.2 man2/pgetcount.2 +man2/ports.2 man2/pgetport.2 +man2/ports.2 man2/preceive.2 +man2/ports.2 man2/preset.2 +man2/ports.2 man2/psend.2 +man2/procsend.2 man2/procreceive.2 +man2/procsend.2 man2/procrecvclr.2 +man2/procsend.2 man2/procrecvtim.2 +man2/read.2 man2/readv.2 +man2/recv.2 man2/recvfrom.2 +man2/recv.2 man2/recvmsg.2 +man2/semaphore.2 man2/scount.2 +man2/semaphore.2 man2/screate.2 +man2/semaphore.2 man2/sdelete.2 +man2/semaphore.2 man2/ssignal.2 +man2/semaphore.2 man2/swait.2 +man2/send.2 man2/sendmsg.2 +man2/send.2 man2/sendto.2 +man2/setpgid.2 man2/setpgrp.2 +man2/setruid.2 man2/setrgid.2 +man2/setuid.2 man2/setegid.2 +man2/setuid.2 man2/seteuid.2 +man2/setuid.2 man2/setgid.2 +man2/sigblock.2 man2/sigmask.2 +man2/stat.2 man2/fstat.2 +man2/stat.2 man2/lstat.2 +man2/statfs.2 man2/fstatfs.2 +man2/truncate.2 man2/ftruncate.2 +man2/wait.2 man2/wait3.2 +man2/wait.2 man2/wait4.2 +man2/wait.2 man2/waitpid.2 +man2/write.2 man2/writev.2 +man3/GSString.3 man3/GIchange.3 +man3/GSString.3 man3/GIfree.3 +man3/GSString.3 man3/GIinit.3 +man3/GSString.3 man3/GOchange.3 +man3/GSString.3 man3/GOfree.3 +man3/GSString.3 man3/GOinit.3 +man3/GSString.3 man3/ResultBuf.3 +man3/GSString.3 man3/__C2GS.3 +man3/GSString.3 man3/__C2GSMALLOC.3 +man3/GSString.3 man3/__GS2C.3 +man3/GSString.3 man3/__GS2CMALLOC.3 +man3/basename.3 man3/dirname.3 +man3/crypt.3 man3/encrypt.3 +man3/crypt.3 man3/setkey.3 +man3/directory.3 man3/closedir.3 +man3/directory.3 man3/dirfd.3 +man3/directory.3 man3/opendir.3 +man3/directory.3 man3/readdir.3 +man3/directory.3 man3/rewinddir.3 +man3/directory.3 man3/seekdir.3 +man3/directory.3 man3/telldir.3 +man3/err.3 man3/err_set_exit.3 +man3/err.3 man3/err_set_file.3 +man3/err.3 man3/errx.3 +man3/err.3 man3/verr.3 +man3/err.3 man3/verrx.3 +man3/err.3 man3/vwarn.3 +man3/err.3 man3/vwarnx.3 +man3/err.3 man3/warn.3 +man3/err.3 man3/warnx.3 +man3/exit.3 man2/_exit.2 +man3/exit.3 man3/rexit.3 +man3/fts.3 man3/fts_children.3 +man3/fts.3 man3/fts_close.3 +man3/fts.3 man3/fts_open.3 +man3/fts.3 man3/fts_read.3 +man3/fts.3 man3/fts_set.3 +man3/getcwd.3 man3/getwd.3 +man3/getenv.3 man3/environInit.3 +man3/getenv.3 man3/environPop.3 +man3/getenv.3 man3/environPush.3 +man3/getenv.3 man3/putenv.3 +man3/getenv.3 man3/setenv.3 +man3/getenv.3 man3/unsetenv.3 +man3/getgrent.3 man3/endgrent.3 +man3/getgrent.3 man3/getgrgid.3 +man3/getgrent.3 man3/getgrnam.3 +man3/getgrent.3 man3/setgrent.3 +man3/getgrent.3 man3/setgroupent.3 +man3/gethostname.3 man3/sethostname.3 +man3/getopt.3 man3/getopt_restart.3 +man3/getpwent.3 man3/endpwent.3 +man3/getpwent.3 man3/getpwnam.3 +man3/getpwent.3 man3/getpwuid.3 +man3/getpwent.3 man3/setpassent.3 +man3/getpwent.3 man3/setpwent.3 +man3/mapErr.3 man3/_mapErr.3 +man3/mapMode.3 man3/_getModeEmulation.3 +man3/mapMode.3 man3/_mapMode2GS.3 +man3/mapMode.3 man3/_mapMode2Unix.3 +man3/mapMode.3 man3/_setModeEmulation.3 +man3/mapPath.3 man3/_mapPath.3 +man3/mapPath.3 man3/_mapPathGS.3 +man3/mapPath.3 man3/_setPathMapping.3 +man3/mktemp.3 man3/mkstemp.3 +man3/parsearg.3 man3/GNO_COMMAND.3 +man3/parsearg.3 man3/GNO_FREEARG.3 +man3/parsearg.3 man3/GNO_PARSEARG.3 +man3/popen.3 man3/pclose.3 +man3/progname.3 man3/__prognameGS.3 +man3/pwcache.3 man3/group_from_gid.3 +man3/pwcache.3 man3/user_from_uid.3 +man3/setjmp.3 man3/_longjmp.3 +man3/setjmp.3 man3/_setjmp.3 +man3/setjmp.3 man3/longjmp.3 +man3/setjmp.3 man3/longjmperror.3 +man3/setjmp.3 man3/siglongjmp.3 +man3/setjmp.3 man3/sigsetjmp.3 +man3/stack.3 man3/_beginStackCheck.3 +man3/stack.3 man3/_endStackCheck.3 +man3/strcasecmp.3 man3/stricmp.3 +man3/strcasecmp.3 man3/strincmp.3 +man3/strcasecmp.3 man3/strncasecmp.3 +man3/strerror.3 man3/errno.3 +man3/strerror.3 man3/perror.3 +man3/stty.3 man3/gtty.3 +man3/syslog.3 man3/closelog.3 +man3/syslog.3 man3/openlog.3 +man3/syslog.3 man3/setlogmask.3 +man3/syslog.3 man3/vsyslog.3 +man3/tmpnam.3 man3/tempnam.3 +man3/tmpnam.3 man3/tmpfile.3 +man3/ttyname.3 man3/isatty.3 +man3/ttyname.3 man3/ttyslot.3