diff options
Diffstat (limited to 'usr/src/man/man3ucb')
23 files changed, 3480 insertions, 0 deletions
diff --git a/usr/src/man/man3ucb/Makefile b/usr/src/man/man3ucb/Makefile new file mode 100644 index 0000000000..b03df0ec32 --- /dev/null +++ b/usr/src/man/man3ucb/Makefile @@ -0,0 +1,47 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3ucb + +MANFILES = dbm.3ucb \ + flock.3ucb \ + fopen.3ucb \ + gettimeofday.3ucb \ + mctl.3ucb \ + nice.3ucb \ + nlist.3ucb \ + printf.3ucb \ + psignal.3ucb \ + rand.3ucb \ + readdir.3ucb \ + scandir.3ucb \ + setjmp.3ucb \ + sigblock.3ucb \ + siginterrupt.3ucb \ + signal.3ucb \ + sigstack.3ucb \ + sigvec.3ucb \ + sleep.3ucb \ + syscall.3ucb \ + times.3ucb \ + wait.3ucb + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man3ucb/dbm.3ucb b/usr/src/man/man3ucb/dbm.3ucb new file mode 100644 index 0000000000..3da661bd4f --- /dev/null +++ b/usr/src/man/man3ucb/dbm.3ucb @@ -0,0 +1,150 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH dbm 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +dbm, dbminit, dbmclose, fetch, store, delete, firstkey, nextkey \- data base +subroutines +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldbm\fR +#include <dbm.h> + +typedef struct { + char *dptr; + int dsize; + }datum; + +\fBint\fR \fBdbminit\fR(\fIfile\fR) +\fBchar *\fR\fIfile\fR; +.fi + +.LP +.nf +\fBint\fR \fBdbmclose\fR(); +.fi + +.LP +.nf +\fBdatum\fR \fBfetch\fR(\fIkey\fR) +\fBdatum\fR \fIkey\fR; +.fi + +.LP +.nf +\fBint\fR \fBstore\fR( \fIkey\fR, \fIdat\fR) +\fBdatum\fR \fIkey\fR, \fIdat\fR; +.fi + +.LP +.nf +\fBint\fR \fBdelete\fR(\fIkey\fR) +\fBdatum\fR \fIkey\fR; +.fi + +.LP +.nf +\fBdatum\fR \fBfirstkey\fR(); +.fi + +.LP +.nf +\fBdatum\fR \fBnextkey\fR(\fIkey\fR) +\fBdatum\fR \fIkey\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBdbm()\fR library has been superseded by \fBndbm\fR (see \fBndbm\fR(3C)). +.sp +.LP +These functions maintain key/content pairs in a data base. The functions will +handle very large (a billion blocks) databases and will access a keyed item in +one or two file system accesses. +.sp +.LP +\fIkey/dat\fR and their content are described by the \fBdatum\fR \fBtypedef\fR. +A \fBdatum\fR specifies a string of \fIdsize\fR bytes pointed to by \fIdptr\fR. +Arbitrary binary data, as well as normal ASCII strings, are allowed. The data +base is stored in two files. One file is a directory containing a bit map and +has \fB\&.dir\fR as its suffix. The second file contains all data and has +\fB\&.pag\fR as its suffix. +.sp +.LP +Before a database can be accessed, it must be opened by \fBdbminit()\fR. At the +time of this call, the files \fIfile\fR\fB\&.dir\fR and \fIfile\fR\fB\&.pag\fR +must exist. An empty database is created by creating zero-length \fB\&.dir\fR +and \fB\&.pag\fR files. +.sp +.LP +A database may be closed by calling \fBdbmclose()\fR. You must close a database +before opening a new one. +.sp +.LP +Once open, the data stored under a key is accessed by \fBfetch()\fR and data is +placed under a key by \fBstore\fR. A key (and its associated contents) is +deleted by \fBdelete()\fR. A linear pass through all keys in a database may be +made, in an (apparently) random order, by use of \fBfirstkey()\fR and +\fBnextkey()\fR. \fBfirstkey()\fR will return the first key in the database. +With any key \fBnextkey()\fR will return the next key in the database. This +code will traverse the data base: +.sp +.in +2 +.nf +for (key = firstkey; key.dptr != NULL; key = nextkey(key)) +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +All functions that return an \fBint\fR indicate errors with negative values. A +zero return indicates no error. Routines that return a \fBdatum\fR indicate +errors with a \fINULL\fR (0) \fIdptr\fR. +.SH SEE ALSO +.sp +.LP +\fBar\fR(1), \fBcat\fR(1), \fBcp\fR(1), \fBtar\fR(1), \fBndbm\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +The \fB\&.pag\fR file will contain holes so that its apparent size may be +larger than its actual content. Older versions of the UNIX operating system may +create real file blocks for these holes when touched. These files cannot be +copied by normal means ( \fBcp\fR(1), \fBcat\fR(1), \fBtar\fR(1), \fBar\fR(1)) +without filling in the holes. +.sp +.LP +\fIdptr\fR pointers returned by these subroutines point into static storage +that is changed by subsequent calls. +.sp +.LP +The sum of the sizes of a key/content pair must not exceed the internal block +size (currently 1024 bytes). Moreover all key/content pairs that hash together +must fit on a single block. \fBstore\fR will return an error in the event that +a disk block fills with inseparable data. +.sp +.LP +\fBdelete()\fR does not physically reclaim file space, although it does make it +available for reuse. +.sp +.LP +The order of keys presented by \fBfirstkey()\fR and \fBnextkey()\fR depends on +a hashing function, not on anything interesting. +.sp +.LP +There are no interlocks and no reliable cache flushing; thus concurrent +updating and reading is risky. +.sp +.LP +The database files (\fIfile\fR\fB\&.dir\fR and \fIfile\fR\fB\&.pag\fR) are +binary and are architecture-specific (for example, they depend on the +architecture's byte order.) These files are not guaranteed to be portable +across architectures. diff --git a/usr/src/man/man3ucb/flock.3ucb b/usr/src/man/man3ucb/flock.3ucb new file mode 100644 index 0000000000..a838b0a153 --- /dev/null +++ b/usr/src/man/man3ucb/flock.3ucb @@ -0,0 +1,154 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH flock 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +flock \- apply or remove an advisory lock on an open file +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR[ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/file.h> + +\fBint\fR \fBflock\fR( \fIfd\fR, \fIoperation\fR) + +\fBint\fR \fIfd\fR, \fIoperation\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBflock()\fR applies or removes an \fIadvisory\fR lock on the file associated +with the file descriptor \fIfd\fR. The compatibility version of \fBflock()\fR +has been implemented on top of \fBfcntl\fR(2) locking. It does not provide +complete binary compatibility. +.sp +.LP +Advisory locks allow cooperating processes to perform consistent operations on +files, but do not guarantee exclusive access (that is, processes may still +access files without using advisory locks, possibly resulting in +inconsistencies). +.sp +.LP +The locking mechanism allows two types of locks: shared locks and exclusive +locks. More than one process may hold a shared lock for a file at any given +time, but multiple exclusive, or both shared and exclusive, locks may not exist +simultaneously on a file. +.sp +.LP +A lock is applied by specifying an \fIoperation\fR parameter \fBLOCK_SH\fR for +a shared lock or \fBLOCK_EX\fR for an exclusive lock. The \fIoperation\fR +parameter may be ORed with \fBLOCK_NB\fR to make the operation non-blocking. To +unlock an existing lock, the \fIoperation\fR should be \fBLOCK_UN.\fR +.sp +.LP +Read permission is required on a file to obtain a shared lock, and write +permission is required to obtain an exclusive lock. Locking a segment that is +already locked by the calling process causes the old lock type to be removed +and the new lock type to take effect. +.sp +.LP +Requesting a lock on an object that is already locked normally causes the +caller to block until the lock may be acquired. If \fBLOCK_NB\fR is included +in \fIoperation\fR, then this will not happen; instead, the call will fail and +the error \fBEWOULDBLOCK\fR will be returned. +.SH RETURN VALUES +.sp +.LP +\fBflock()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +on success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +on failure and sets \fBerrno\fR to indicate the error. +.RE + +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The argument \fIfd\fR is an invalid descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +\fIoperation\fR is not a valid argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 15n +.rt +The argument \fIfd\fR refers to an object other than a file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 15n +.rt +The file is locked and the \fBLOCK_NB\fR option was specified. +.RE + +.SH SEE ALSO +.sp +.LP +\fBlockd\fR(1M), \fBchmod\fR(2), \fBclose\fR(2), \fBdup\fR(2), \fBexec\fR(2), +\fBfcntl\fR(2), \fBfork\fR(2), \fBopen\fR(2), \fBlockf\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +Locks are on files, not file descriptors. That is, file descriptors duplicated +through \fBdup\fR(2) or \fBfork\fR(2) do not result in multiple instances of a +lock, but rather multiple references to a single lock. If a process holding a +lock on a file forks and the child explicitly unlocks the file, the parent will +lose its lock. Locks are not inherited by a child process. +.sp +.LP +Processes blocked awaiting a lock may be awakened by signals. +.sp +.LP +Mandatory locking may occur, depending on the mode bits of the file. See +\fBchmod\fR(2). +.sp +.LP +Locks obtained through the \fBflock()\fR mechanism under SunOS 4.1 were known +only within the system on which they were placed. This is no longer true. diff --git a/usr/src/man/man3ucb/fopen.3ucb b/usr/src/man/man3ucb/fopen.3ucb new file mode 100644 index 0000000000..d105dbf210 --- /dev/null +++ b/usr/src/man/man3ucb/fopen.3ucb @@ -0,0 +1,152 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fopen 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +fopen, freopen \- open a stream +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <stdio.h> + +\fBFILE *\fR\fBfopen\fR(\fIfile\fR, \fImode\fR) +\fBconst char *\fR\fIfile\fR, \fB*\fR\fImode\fR; +.fi + +.LP +.nf +\fBFILE *\fR\fBfreopen\fR(\fIfile\fR, \fImode\fR, \fIiop\fR) +\fBconst char *\fR\fIfile\fR, \fB*\fR\fImode\fR; +\fBregister FILE *\fR\fIiop\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfopen()\fR function opens the file specified by \fIfile\fR and +associates a stream with it. If the open succeeds, \fBfopen()\fR returns a +pointer to be used to identify the stream in subsequent operations. The +\fIfile\fR argument points to a character string that contains the name of the +file to be opened. The \fImode\fR argument is a character string having one of +the following values: +.sp +.ne 2 +.mk +.na +\fB\fBr\fR\fR +.ad +.RS 6n +.rt +open for reading +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBw\fR\fR +.ad +.RS 6n +.rt +truncate or create for writing +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR\fR +.ad +.RS 6n +.rt +append: open for writing at end of file, or create for writing +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBr+\fR\fR +.ad +.RS 6n +.rt +open for update (reading and writing) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBw+\fR\fR +.ad +.RS 6n +.rt +truncate or create for update +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa+\fR\fR +.ad +.RS 6n +.rt +append; open or create for update at \fBEOF\fR +.RE + +.sp +.LP +The \fBfreopen()\fR function opens the file specified by \fIfile\fR and +associates the stream pointed to by \fIiop\fR with it. The \fImode\fR argument +is used just as in \fBfopen()\fR. The original stream is closed, regardless of +whether the open ultimately succeeds. If the open succeeds, \fBfreopen()\fR +returns the original value of \fIiop\fR. +.sp +.LP +The \fBfreopen()\fR function is typically used to attach the pre-opened streams +associated with\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR to other files. +.sp +.LP +When a file is opened for update, both input and output can be performed on the +resulting stream. Output cannot be directly followed by input without an +intervening \fBfseek\fR(3C) or \fBrewind\fR(3C). Input cannot be directly +followed by output without an intervening \fBfseek\fR(3C) or \fBrewind\fR(3C). +An input operation that encounters \fBEOF will fail.\fR +.SH RETURN VALUES +.sp +.LP +The \fBfopen()\fR and \fBfreopen()\fR functions return a \fINULL\fR pointer on +failure. +.SH USAGE +.sp +.LP +The \fBfopen()\fR and \fBfreopen()\fR functions have transitional interfaces +for 64-bit file offsets. See \fBlf64\fR(5). +.SH SEE ALSO +.sp +.LP +\fBopen\fR(2), \fBfclose\fR(3C), \fBfopen\fR(3C), \fBfreopen\fR(3C), +\fBfseek\fR(3C), \fBmalloc\fR(3C), \fBrewind\fR(3C), \fBlf64\fR(5) +.SH NOTES +.sp +.LP +Use of these functions should be restricted to applications written on BSD +platforms. Use of these functions with any of the system libraries or in +multithreaded applications is unsupported. +.sp +.LP +To support the same number of open files as the system, \fBfopen()\fR must +allocate additional memory for data structures using \fBmalloc\fR(3C) after 64 +files have been opened. This confuses some programs that use their own memory +allocators. +.sp +.LP +The \fBfopen()\fR and \fBfreopen()\fR functions differ from the standard I/O +functions \fBfopen\fR(3C) and \fBfreopen\fR(3C). The standard I/O functions +distinguish binary from text files with an additional use of '\fBb\fR' as part +of the \fImode\fR, enabling portability of \fBfopen\fR(3C) and +\fBfreopen\fR(3C) beyond SunOS 4.\fIx\fR systems. diff --git a/usr/src/man/man3ucb/gettimeofday.3ucb b/usr/src/man/man3ucb/gettimeofday.3ucb new file mode 100644 index 0000000000..3a946d6576 --- /dev/null +++ b/usr/src/man/man3ucb/gettimeofday.3ucb @@ -0,0 +1,103 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH gettimeofday 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +gettimeofday, settimeofday \- get or set the date and time +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/time.h> + +\fBint\fR \fBgettimeofday\fR(\fItp\fR, \fItzp\fR) +\fBstruct timeval *\fR\fItzp\fR; +\fBstruct timezone *\fR\fItzp\fR; +.fi + +.LP +.nf +\fBint\fR \fBsettimeofday\fR(\fItp\fR, \fItzp\fR) +\fBstruct timeval *\fR\fItzp\fR; +\fBstruct timezone *\fR\fItzp\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The system's notion of the current Greenwich time is obtained with the +\fBgettimeofday()\fR call, and set with the \fBsettimeofday()\fR call. The +current time is expressed in elapsed seconds and microseconds since 00:00 +\fBGMT,\fR January 1, 1970 (zero hour). The resolution of the system clock is +hardware dependent; the time may be updated continuously, or in clock ticks. +.sp +.in +2 +.nf +long tv_sec; /* seconds since Jan. 1, 1970 */ +long tv_usec; /* and microseconds */ +.fi +.in -2 + +.sp +.LP +\fItp\fR points to a \fBtimeval\fR structure, which includes the following +members: +.sp +.LP +If \fItp\fR is a \fINULL\fR pointer, the current time information is not +returned or set. +.sp +.LP +\fItzp\fR is an obsolete pointer formerly used to get and set timezone +information. \fItzp\fR is now ignored. Timezone information is now handled +using the \fBTZ\fR environment variable; see \fBTIMEZONE\fR(4). +.sp +.LP +Only the privileged user may set the time of day. +.SH RETURN VALUES +.sp +.LP +A \fB\(mi1\fR return value indicates an error occurred; in this case an error +code is stored in the global variable \fBerrno\fR. +.SH ERRORS +.sp +.LP +The following error codes may be set in \fBerrno\fR: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fItp\fR specifies an invalid time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +A user other than the privileged user attempted to set the time. +.RE + +.SH SEE ALSO +.sp +.LP +\fBadjtime\fR(2), \fBctime\fR(3C), \fBgettimeofday\fR(3C), \fBTIMEZONE\fR(4) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +\fItzp\fR is ignored in SunOS 5.\fIX\fR releases. +.sp +.LP +\fBtv_usec\fR is always 0. diff --git a/usr/src/man/man3ucb/mctl.3ucb b/usr/src/man/man3ucb/mctl.3ucb new file mode 100644 index 0000000000..0969ece976 --- /dev/null +++ b/usr/src/man/man3ucb/mctl.3ucb @@ -0,0 +1,270 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mctl 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +mctl \- memory management control +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/types.h> +#include <sys/mman.h> + +\fBint\fR \fBmctl\fR(\fIaddr\fR, \fIlen\fR, \fIfunction\fR, \fIarg\fR) +\fBcaddr_t\fR \fIaddr\fR; +\fBsize_t\fR \fIlen\fR; +\fBint\fR \fIfunction\fR; +\fBint\fR \fIarg\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBmctl()\fR applies a variety of control functions over pages identified by +the mappings established for the address range [\fIaddr, addr + len\fR). The +function to be performed is identified by the argument \fIfunction\fR. Valid +functions are defined in \fB<mman.h>\fR as follows: +.sp +.ne 2 +.mk +.na +\fB\fBMC_LOCK\fR\fR +.ad +.RS 15n +.rt +Lock the pages in the range in memory. This function is used to support +\fBmlock()\fR. See \fBmlock\fR(3C) for semantics and usage. \fIarg\fR is +ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMC_LOCKAS\fR\fR +.ad +.RS 15n +.rt +Lock the pages in the address space in memory. This function is used to +support \fBmlockall()\fR. See \fBmlockall\fR(3C) for semantics and usage. +\fIaddr\fR and \fIlen\fR are ignored. \fIarg\fR is an integer built from the +flags: +.sp +.ne 2 +.mk +.na +\fB\fBMCL_CURRENT\fR\fR +.ad +.RS 15n +.rt +Lock current mappings +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMCL_FUTURE\fR\fR +.ad +.RS 15n +.rt +Lock future mappings +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMC_SYNC\fR\fR +.ad +.RS 15n +.rt +Synchronize the pages in the range with their backing storage. Optionally +invalidate cache copies. This function is used to support \fBmsync()\fR. See +\fBmsync\fR(3C) for semantics and usage. \fIarg\fR is used to represent the +\fIflags\fR argument to \fBmsync()\fR. It is constructed from an OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBMS_SYNC\fR\fR +.ad +.RS 17n +.rt +Synchronized write +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMS_ASYNC\fR\fR +.ad +.RS 17n +.rt +Return immediately +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMS_INVALIDATE\fR\fR +.ad +.RS 17n +.rt +Invalidate mappings +.RE + +\fBMS_ASYNC\fR returns after all \fBI/O\fR operations are scheduled. +\fBMS_SYNC\fR does not return until all \fBI/O\fR operations are complete. +Specify exactly one of \fBMS_ASYNC\fR or \fBMS_SYNC\fR. \fBMS_INVALIDATE\fR +invalidates all cached copies of data from memory, requiring them to be +re-obtained from the object's permanent storage location upon the next +reference. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMC_UNLOCK\fR\fR +.ad +.RS 15n +.rt +Unlock the pages in the range. This function is used to support +\fBmunlock()\fR. \fIarg\fR is ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMC_UNLOCKAS\fR\fR +.ad +.RS 15n +.rt +Remove address space memory lock, and locks on all current mappings. This +function is used to support \fBmunlockall()\fR. \fIaddr\fR and \fIlen\fR must +have the value 0. \fIarg\fR is ignored. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBmctl()\fR returns \fB0\fR on success, \fB\(mi1\fR on failure. +.SH ERRORS +.sp +.LP +\fBmctl()\fR fails if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Some or all of the memory identified by the operation could not be locked due +to insufficient system resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBUSY\fR\fR +.ad +.RS 10n +.rt +\fBMS_INVALIDATE\fR was specified and one or more of the pages is locked in +memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIaddr\fR is not a multiple of the page size as returned by +\fBgetpagesize()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIaddr\fR and/or \fIlen\fR do not have the value 0 when \fBMC_LOCKAS\fR or +\fBMC_UNLOCKAS\fR are specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIarg\fR is not valid for the function specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +Addresses in the range [\fIaddr, addr + len\fR) are invalid for the address +space of a process, or specify one or more pages which are not mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 10n +.rt +The process's effective user \fBID\fR is not superuser and one of \fBMC_LOCK +MC_LOCKAS\fR, \fBMC_UNLOCK\fR, or \fBMC_UNLOCKAS\fR was specified. +.RE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBmemcntl\fR(2), \fBgetpagesize\fR(3C), \fBmlock\fR(3C), +\fBmlockall\fR(3C), \fBmsync\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. diff --git a/usr/src/man/man3ucb/nice.3ucb b/usr/src/man/man3ucb/nice.3ucb new file mode 100644 index 0000000000..3ff8c79519 --- /dev/null +++ b/usr/src/man/man3ucb/nice.3ucb @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nice 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +nice \- change priority of a process +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include<unistd.h> + +\fBint\fR \fBnice\fR(\fIincr\fR) +\fBint\fR \fIincr\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The scheduling priority of the process is augmented by \fIincr\fR. Positive +priorities get less service than normal. Priority 10 is recommended to users +who wish to execute long-running programs without undue impact on system +performance. +.sp +.LP +Negative increments are illegal, except when specified by the privileged user. +The priority is limited to the range \(mi20 (most urgent) to 20 (least). +Requests for values above or below these limits result in the scheduling +priority being set to the corresponding limit. +.sp +.LP +The priority of a process is passed to a child process by \fBfork\fR(2). For a +privileged process to return to normal priority from an unknown state, +\fBnice()\fR should be called successively with arguments \(mi40 (goes to +priority \(mi20 because of truncation), 20 (to get to 0), then 0 (to maintain +compatibility with previous versions of this call). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBnice()\fR returns \fB0\fR. Otherwise, a value of +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The priority is not changed if: +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 9n +.rt +The value of \fIincr\fR specified was negative, and the effective user \fBID\fR +is not the privileged user. +.RE + +.SH SEE ALSO +.sp +.LP +\fBnice\fR(1), \fBrenice\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), +\fBgetpriority\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-threaded applications is unsupported. diff --git a/usr/src/man/man3ucb/nlist.3ucb b/usr/src/man/man3ucb/nlist.3ucb new file mode 100644 index 0000000000..d43ac1a634 --- /dev/null +++ b/usr/src/man/man3ucb/nlist.3ucb @@ -0,0 +1,55 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nlist 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +nlist \- get entries from symbol table +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <nlist.h> + +\fBint\fR \fBnlist\fR(\fIfilename\fR, \fInl\fR) +\fBchar *\fR\fIfilename\fR; +\fBstruct nlist *\fR\fInl\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBnlist()\fR examines the symbol table from the executable image whose name is +pointed to by \fIfilename\fR, and selectively extracts a list of values and +puts them in the array of \fBnlist\fR structures pointed to by \fInl\fR. The +name list pointed to by \fInl\fR consists of an array of structures containing +names, types and values. The \fBn_name\fR field of each such structure is taken +to be a pointer to a character string representing a symbol name. The list is +terminated by an entry with a \fINULL\fR pointer (or a pointer to a \fINULL\fR +string) in the \fBn_name\fR field. For each entry in \fInl\fR, if the named +symbol is present in the executable image's symbol table, its value and type +are placed in the \fBn_value\fR and \fBn_type\fR fields. If a symbol cannot be +located, the corresponding \fBn_type\fR field of \fInl\fR is set to zero. +.SH RETURN VALUES +.sp +.LP +Upon normal completion, \fBnlist()\fR returns the number of symbols that were +not located in the symbol table. If an error occurs, \fBnlist()\fR returns +\(mi1 and sets all of the \fBn_type\fR fields in members of the array pointed +to by \fInl\fR to zero. +.SH SEE ALSO +.sp +.LP +\fBnlist\fR(3ELF), \fBa.out\fR(4) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +Only the \fBn_value\fR field is compatibly set. Other fields in the +\fBnlist\fR structure are filled with the ELF (Executable and Linking Format) +values (see \fBnlist\fR(3ELF) and \fBa.out\fR(4)). diff --git a/usr/src/man/man3ucb/printf.3ucb b/usr/src/man/man3ucb/printf.3ucb new file mode 100644 index 0000000000..cf104cdacc --- /dev/null +++ b/usr/src/man/man3ucb/printf.3ucb @@ -0,0 +1,373 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH printf 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +printf, fprintf, sprintf, vprintf, vfprintf, vsprintf \- formatted output +conversion +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [\fIflag\fR ...] \fIfile\fR ... +#include <stdio.h> + +\fBint\fR \fBprintf\fR(\fIformat\fR, \fI\&...\fR) +\fBconst char *\fR\fIformat\fR; +.fi + +.LP +.nf +\fBint\fR \fBfprintf\fR(\fIstream\fR, \fIformat\fR, \fIva_list\fR) +\fBFILE *\fR\fIstream\fR; +\fBchar *\fR\fIformat\fR; +\fIva_dcl\fR; +.fi + +.LP +.nf +\fBchar *\fR\fBsprintf\fR(\fIs\fR, \fIformat\fR, \fIva_list\fR) +\fBchar *\fR\fIs\fR, \fB*\fR\fIformat\fR; +\fIva_dcl\fR; +.fi + +.LP +.nf +\fBint\fR \fBvprintf\fR(\fIformat\fR, \fIap\fR) +\fBchar *\fR\fIformat\fR; +\fBva_list\fR \fIap\fR; +.fi + +.LP +.nf +\fBint\fR \fBvfprintf\fR(\fIstream\fR, \fIformat\fR, \fIap\fR) +\fBFILE *\fR\fIstream\fR; +\fBchar *\fR\fIformat\fR; +\fBva_list\fR \fIap\fR; +.fi + +.LP +.nf +\fBchar *\fR\fBvsprintf\fR(\fIs\fR, \fIformat\fR, \fIap\fR) +\fBchar *\fR\fIs\fR, \fB*\fR\fIformat\fR; +\fBva_list\fR \fIap\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBprintf()\fR places output on the standard output stream \fBstdout\fR. +\fBfprintf()\fR places output on the named output \fIstream\fR. \fBsprintf()\fR +places "output," followed by the \fINULL\fR character (\fB\e0\fR), in +consecutive bytes starting at *\fIs\fR; it is the user's responsibility to +ensure that enough storage is available. +.sp +.LP +\fBvprintf()\fR, \fBvfprintf()\fR, and \fBvsprintf()\fR are the same as +\fBprintf()\fR, \fBfprintf()\fR, and \fBsprintf()\fR respectively, except that +instead of being called with a variable number of arguments, they are called +with an argument list as defined by \fB<varargs.h>\fR. +.sp +.LP +Each of these functions converts, formats, and prints its \fIarg\fRs under +control of the \fIformat\fR. The \fIformat\fR is a character string which +contains two types of objects: plain characters, which are simply copied to the +output stream, and conversion specifications, each of which causes conversion +and printing of zero or more \fIarg\fRs. The results are undefined if there are +insufficient \fIarg\fRs for the format. If the format is exhausted while +\fIarg\fRs remain, the excess \fIarg\fRs are simply ignored. +.sp +.LP +Each conversion specification is introduced by the character \fB%\fR. After the +\fB%\fR, the following appear in sequence: +.RS +4 +.TP +.ie t \(bu +.el o +Zero or more \fIflags\fR, which modify the meaning of the conversion +specification. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional decimal digit string specifying a minimum \fIfield width\fR. If the +converted value has fewer characters than the field width, it will be padded on +the left (or right, if the left-adjustment flag `\fB\(mi\fR\&', described +below, has been given) to the field width. The padding is with blanks unless +the field width digit string starts with a zero, in which case the padding is +with zeros. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A \fIprecision\fR that gives the minimum number of digits to appear for the +\fBd\fR, \fBi\fR, \fBo\fR, \fBu\fR, \fBx\fR, or \fBX\fR conversions, the number +of digits to appear after the decimal point for the \fBe\fR, \fBE\fR, and +\fBf\fR conversions, the maximum number of significant digits for the \fBg\fR +and \fBG\fR conversion, or the maximum number of characters to be printed from +a string in \fBs\fR conversion. The precision takes the form of a period +(\fB\&.\fR) followed by a decimal digit string; a \fINULL\fR digit string is +treated as zero. Padding specified by the precision overrides the padding +specified by the field width. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +An optional \fBl\fR (ell) specifying that a following \fBd\fR, \fBi\fR, +\fBo\fR, \fBu\fR, \fBx\fR, or \fBX\fR conversion character applies to a long +integer \fIarg\fR. An \fBl\fR before any other conversion character is ignored. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A character that indicates the type of conversion to be applied. +.RE +.sp +.LP +A field width or precision or both may be indicated by an asterisk (\fB*\fR) +instead of a digit string. In this case, an integer \fIarg\fR supplies the +field width or precision. The \fIarg\fR that is actually converted is not +fetched until the conversion letter is seen, so the \fIarg\fRs specifying field +width or precision must appear \fIbefore\fR the \fIarg\fR (if any) to be +converted. A negative field width argument is taken as a `\fB\(mi\fR\&' flag +followed by a positive field width. If the precision argument is negative, it +will be changed to zero. +.sp +.LP +The flag characters and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fB\(mi\fR\fR +.ad +.RS 9n +.rt +The result of the conversion will be left-justified within the field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB+\fR\fR +.ad +.RS 9n +.rt +The result of a signed conversion will always begin with a sign (\fB+\fR or +\fB\(mi\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fBblank\fR +.ad +.RS 9n +.rt +If the first character of a signed conversion is not a sign, a blank will be +prefixed to the result. This implies that if the blank and \fB+\fR flags both +appear, the blank flag will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB#\fR\fR +.ad +.RS 9n +.rt +This flag specifies that the value is to be converted to an "alternate form." +For \fBc\fR, \fBd\fR, \fBi\fR, \fBs\fR, and \fBu\fR conversions, the flag has +no effect. For \fBo\fR conversion, it increases the precision to force the +first digit of the result to be a zero. For \fBx\fR or \fBX\fR conversion, a +non-zero result will have \fB0x\fR or \fB0X\fR prefixed to it. For \fBe\fR, +\fBE\fR, \fBf\fR, \fBg\fR, and \fBG\fR conversions, the result will always +contain a decimal point, even if no digits follow the point (normally, a +decimal point appears in the result of these conversions only if a digit +follows it). For \fBg\fR and \fBG\fR conversions, trailing zeroes will +\fInot\fR be removed from the result (which they normally are). +.RE + +.sp +.LP +The conversion characters and their meanings are: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR,\fBi\fR,\fBo\fR,\fBu\fR,\fBx\fR,\fBX\fR\fR +.ad +.RS 15n +.rt +The integer \fIarg\fR is converted to signed decimal (\fBd\fR or \fBi\fR), +unsigned octal (\fBo\fR), unsigned decimal (\fBu\fR), or unsigned hexadecimal +notation (\fBx\fR and \fBX\fR), respectively; the letters \fBabcdef\fR are used +for \fBx\fR conversion and the letters \fBABCDEF\fR for \fBX\fR conversion. The +precision specifies the minimum number of digits to appear; if the value being +converted can be represented in fewer digits, it will be expanded with leading +zeroes. (For compatibility with older versions, padding with leading zeroes may +alternatively be specified by prepending a zero to the field width. This does +not imply an octal value for the field width.) The default precision is 1. The +result of converting a zero value with a precision of zero is a \fINULL\fR +string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBf\fR\fR +.ad +.RS 15n +.rt +The float or double \fIarg\fR is converted to decimal notation in the style +[\fB\(mi\fR]\fIddd\fR\fB\&.\fR\fIddd\fR where the number of digits after the +decimal point is equal to the precision specification. If the precision is +missing, 6 digits are given; if the precision is explicitly 0, no digits and no +decimal point are printed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBe\fR,\fBE\fR\fR +.ad +.RS 15n +.rt +The float or double \fIarg\fR is converted in the style +[\fB\(mi\fR]\fId\fR\fB\&.\fR\fIddd\fR\fBe\(+-\fR\fIddd\fR, where there is one +digit before the decimal point and the number of digits after it is equal to +the precision; when the precision is missing, 6 digits are produced; if the +precision is zero, no decimal point appears. The \fBE\fR format code will +produce a number with \fBE\fR instead of \fBe\fR introducing the exponent. The +exponent always contains at least two digits. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBg\fR,\fBG\fR\fR +.ad +.RS 15n +.rt +The float or double \fIarg\fR is printed in style \fBf\fR or \fBe\fR (or in +style \fBE\fR in the case of a \fBG\fR format code), with the precision +specifying the number of significant digits. The style used depends on the +value converted: style \fBe\fR or \fBE\fR will be used only if the exponent +resulting from the conversion is less than \(mi4 or greater than the precision. +Trailing zeroes are removed from the result; a decimal point appears only if it +is followed by a digit. +.RE + +.sp +.LP +The \fBe\fR, \fBE f\fR, \fBg,\fR and \fBG\fR formats print \fBIEEE\fR +indeterminate values (infinity or not-a-number) as "Infinity" or "NaN" +respectively. +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 5n +.rt +The character \fIarg\fR is printed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 5n +.rt +The \fIarg\fR is taken to be a string (character pointer) and characters from +the string are printed until a \fINULL\fR character (\fB\e0\fR) is encountered +or until the number of characters indicated by the precision specification is +reached. If the precision is missing, it is taken to be infinite, so all +characters up to the first \fINULL\fR character are printed. A \fINULL\fR value +for \fIarg\fR will yield undefined results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 5n +.rt +Print a \fB%\fR; no argument is converted. +.RE + +.sp +.LP +In no case does a nonexistent or small field width cause truncation of a field; +if the result of a conversion is wider than the field width, the field is +simply expanded to contain the conversion result. Padding takes place only if +the specified field width exceeds the actual width. Characters generated by +\fBprintf()\fR and \fBfprintf()\fR are printed as if \fBputc\fR(3C) had been +called. +.SH RETURN VALUES +.sp +.LP +Upon success, \fBprintf()\fR and \fBfprintf()\fR return the number of +characters transmitted, excluding the null character. \fBvprintf()\fR and +\fBvfprintf()\fR return the number of characters transmitted. \fBsprintf()\fR +and \fBvsprintf()\fR always return \fIs\fR. If an output error is encountered, +\fBprintf()\fR, \fBfprint()\fR, \fBvprintf()\fR, and \fBvfprintf()\fR return +EOF. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples of the \fBprintf\fR Command To Print a Date and Time +.sp +.LP +To print a date and time in the form "Sunday, July 3, 10:02," where +\fIweekday\fR and \fImonth\fR are pointers to \fINULL\fR-terminated strings: + +.sp +.in +2 +.nf +printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min); +.fi +.in -2 + +.LP +\fBExample 2 \fRExamples of the \fBprintf\fR Command To Print to Five Decimal +Places +.sp +.LP +To print to five decimal places: + +.sp +.in +2 +.nf +printf("pi \|= \|%.5f", \|4 * atan(1. 0)); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBeconvert\fR(3C), \fBputc\fR(3C), \fBscanf\fR(3C), \fBvprintf\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +Very wide fields (>128 characters) fail. diff --git a/usr/src/man/man3ucb/psignal.3ucb b/usr/src/man/man3ucb/psignal.3ucb new file mode 100644 index 0000000000..786a5ed0d2 --- /dev/null +++ b/usr/src/man/man3ucb/psignal.3ucb @@ -0,0 +1,45 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH psignal 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +psignal, sys_siglist \- system signal messages +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... + +\fBvoid\fR \fBpsignal\fR(\fIsig\fR, \fIs\fR) +\fBunsigned\fR \fIsig\fR; +\fBchar *\fR\fIs\fR; +\fBchar *\fR\fIsys_siglist\fR[]; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBpsignal()\fR produces a short message on the standard error file describing +the indicated signal. First the argument string \fIs\fR is printed, then a +colon, then the name of the signal and a \fBNEWLINE.\fR Most usefully, the +argument string is the name of the program which incurred the signal. The +signal number should be from among those found in \fB<signal.h>\fR. +.sp +.LP +To simplify variant formatting of signal names, the vector of message strings +\fBsys_siglist\fR is provided; the signal number can be used as an index in +this table to get the signal name without the newline. The define \fBNSIG\fR +defined in \fB<signal.h>\fR is the number of messages provided for in the +table; it should be checked because new signals may be added to the system +before they are added to the table. +.SH SEE ALSO +.sp +.LP +\fBperror\fR(3C), \fBsignal\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. diff --git a/usr/src/man/man3ucb/rand.3ucb b/usr/src/man/man3ucb/rand.3ucb new file mode 100644 index 0000000000..be78f1351e --- /dev/null +++ b/usr/src/man/man3ucb/rand.3ucb @@ -0,0 +1,51 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rand 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +rand, srand \- simple random number generator +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... + +int \fBrand\fR(); +.fi + +.LP +.nf +\fBint\fR \fBsrand\fR(\fIseed\fR) +\fBunsigned\fR \fIseed\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBrand()\fR uses a multiplicative congruential random number generator with +period 2^32 to return successive pseudo-random numbers in the range from 0 to +2^31 \(mi\|1. +.sp +.LP +\fBsrand()\fR can be called at any time to reset the random-number generator to +a random starting point. The generator is initially seeded with a value of 1. +.SH SEE ALSO +.sp +.LP +\fBdrand48\fR(3C), \fBrand\fR(3C), \fBrandom\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +The spectral properties of \fBrand()\fR leave a great deal to be desired. +\fBdrand48\fR(3C) and \fBrandom\fR(3C) provide much better, though more +elaborate, random-number generators. +.sp +.LP +The low bits of the numbers generated are not very random; use the middle bits. +In particular the lowest bit alternates between 0 and 1. diff --git a/usr/src/man/man3ucb/readdir.3ucb b/usr/src/man/man3ucb/readdir.3ucb new file mode 100644 index 0000000000..0e27da0595 --- /dev/null +++ b/usr/src/man/man3ucb/readdir.3ucb @@ -0,0 +1,249 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH readdir 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +readdir \- read a directory entry +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/types.h> +#include <sys/dir.h> + +\fBstruct direct *\fR\fBreaddir\fR(\fIdirp\fR) +\fBDIR *\fR\fIdirp\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBreaddir()\fR function returns a pointer to a structure representing the +directory entry at the current position in the directory stream to which +\fIdirp\fR refers, and positions the directory stream at the next entry, except +on read-only file systems. It returns a \fINULL\fR pointer upon reaching the +end of the directory stream, or upon detecting an invalid location in the +directory. The \fBreaddir()\fR function shall not return directory entries +containing empty names. It is unspecified whether entries are returned for +dot \fB(\fR.\fB)\fR or dot-dot \fB(\fR.\|.\fB)\fR. The pointer returned by +\fBreaddir()\fR points to data that may be overwritten by another call to +\fBreaddir()\fR on the same directory stream. This data shall not be +overwritten by another call to \fBreaddir()\fR on a different directory +stream. The \fBreaddir()\fR function may buffer several directory entries per +actual read operation. The \fBreaddir()\fR function marks for update the +\fIst_atime\fR field of the directory each time the directory is actually read. +.SH RETURN VALUES +.sp +.LP +The \fBreaddir()\fR function returns \fINULL\fR on failure and sets \fBerrno\fR +to indicate the error. +.SH ERRORS +.sp +.LP +The \fBreaddir()\fR function will fail if one or more of the following are +true: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +Mandatory file/record locking was set, \fBO_NDELAY\fR or \fBO_NONBLOCK\fR was +set, and there was a blocking record lock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +Total amount of system memory available when reading using raw I/O is +temporarily insufficient. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +No data is waiting to be read on a file associated with a tty device and +\fBO_NONBLOCK\fR was set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 13n +.rt +No message is waiting to be read on a stream and \fBO_NDELAY\fR or +\fBO_NONBLOCK\fR was set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The file descriptor determined by the \fBDIR\fR stream is no longer valid. This +results if the \fBDIR\fR stream has been closed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADMSG\fR\fR +.ad +.RS 13n +.rt +Message waiting to be read on a stream is not a data message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDEADLK\fR\fR +.ad +.RS 13n +.rt +The \fBread()\fR was going to go to sleep and cause a deadlock to occur. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 13n +.rt +\fIbuf\fR points to an illegal address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 13n +.rt +A signal was caught during the \fBread()\fR or \fBreadv()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +Attempted to read from a stream linked to a multiplexor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 13n +.rt +A physical I/O error has occurred, or the process is in a background process +group and is attempting to read from its controlling terminal, and either the +process is ignoring or blocking the \fBSIGTTIN\fR signal or the process group +of the process is orphaned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 13n +.rt +The current file pointer for the directory is not located at a valid entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOLCK\fR\fR +.ad +.RS 13n +.rt +The system record lock table was full, so the \fBread()\fR or \fBreadv()\fR +could not go to sleep until the blocking record lock was removed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOLINK\fR\fR +.ad +.RS 13n +.rt +\fIfildes\fR is on a remote machine and the link to that machine is no longer +active. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 13n +.rt +The device associated with \fIfildes\fR is a block special or character +special file and the value of the file pointer is out of range. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOVERFLOW\fR\fR +.ad +.RS 13n +.rt +The value of the \fBdirect\fR structure member \fBd_ino\fR cannot be +represented in an \fBino_t\fR. +.RE + +.SH USAGE +.sp +.LP +The \fBreaddir()\fR function has a transitional interface for 64-bit file +offsets. See \fBlf64\fR(5). +.SH SEE ALSO +.sp +.LP +\fBgetdents\fR(2), \fBreaddir\fR(3C), \fBscandir\fR(3UCB), \fBlf64\fR(5) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +\fBBSD\fR platforms. Use of these interfaces with any of the system libraries +or in multi-thread applications is unsupported. diff --git a/usr/src/man/man3ucb/scandir.3ucb b/usr/src/man/man3ucb/scandir.3ucb new file mode 100644 index 0000000000..8269e60c60 --- /dev/null +++ b/usr/src/man/man3ucb/scandir.3ucb @@ -0,0 +1,71 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scandir 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +scandir, alphasort \- scan a directory +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR... ] \fIfile\fR... +#include <sys/types.h> +#include <sys/dir.h> + +\fBint\fR \fBscandir\fR(\fIdirname\fR, \fInamelist\fR, \fIselect\fR, \fIdcomp\fR) +\fBchar *\fR\fIdirname\fR; +\fBstruct direct *\fR(*\fInamelist\fR[]); +\fBint\fR (\fB*\fR\fIselect\fR(), (\fB*\fR\fIdcomp\fR)(); +.fi + +.LP +.nf +\fBint\fR \fBalphasort\fR(\fId1\fR, \fId2\fR) +\fBstruct direct **\fR\fId1\fR, \fB**\fR\fId2\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBscandir()\fR function reads the directory \fIdirname\fR and builds an +array of pointers to directory entries using \fBmalloc\fR(3C). The second +parameter is a pointer to an array of structure pointers. The third parameter +is a pointer to a routine which is called with a pointer to a directory entry +and should return a non zero value if the directory entry should be included in +the array. If this pointer is \fINULL\fR, then all the directory entries will +be included. The last argument is a pointer to a routine which is passed to +\fBqsort\fR(3C), which sorts the completed array. If this pointer is +\fINULL\fR, the array is not sorted. +.sp +.LP +The \fBalphasort()\fR function sorts the array alphabetically. +.SH RETURN VALUES +.sp +.LP +The \fBscandir()\fR function returns the number of entries in the array and a +pointer to the array through the parameter \fInamelist\fR. The \fBscandir()\fR +function returns \fB\(mi1\fR if the directory cannot be opened for reading or +if \fBmalloc\fR(3C) cannot allocate enough memory to hold all the data +structures. +.sp +.LP +The \fBalphasort()\fR function returns an integer greater than, equal to, or +less than 0 if the directory entry name pointed to by \fId1\fR is greater than, +equal to, or less than the directory entry name pointed to by \fId2\fR. +.SH USAGE +.sp +.LP +The \fBscandir()\fR and \fBalphasort()\fR functions have transitional +interfaces for 64-bit file offsets. See \fBlf64\fR(5). +.SH SEE ALSO +.sp +.LP +\fBgetdents\fR(2), \fBmalloc\fR(3C), \fBqsort\fR(3C), \fBreaddir\fR(3UCB), +\fBreaddir\fR(3C), \fBlf64\fR(5) +.SH NOTES +.sp +.LP +Use of these functions should be restricted to applications written on +\fBBSD\fR platforms. Use of these functions with any of the system libraries +or in multithreaded applications is unsupported. diff --git a/usr/src/man/man3ucb/setjmp.3ucb b/usr/src/man/man3ucb/setjmp.3ucb new file mode 100644 index 0000000000..fec0256b8b --- /dev/null +++ b/usr/src/man/man3ucb/setjmp.3ucb @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH setjmp 3UCB "7 Apr 1993" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +setjmp, longjmp, _setjmp, _longjmp \- non-local goto +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <setjmp.h> + +\fBint\fR \fBsetjmp\fR(\fIenv\fR) +\fBjmp_buf\fR \fIenv\fR; +.fi + +.LP +.nf +\fBvoid\fR \fBlongjmp\fR(\fIenv\fR, \fIval\fR) +\fBjmp_buf\fR \fIenv\fR; +\fBint\fR \fIval\fR; +.fi + +.LP +.nf +\fBint\fR \fB_setjmp\fR(\fIenv\fR) +\fBjmp_buf\fR \fIenv\fR; +.fi + +.LP +.nf +\fBvoid\fR \fB_longjmp\fR(\fIenv\fR, \fIval\fR) +\fBjmp_buf\fR \fIenv\fR; +\fBint\fR \fIval\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetjmp()\fR and \fBlongjmp()\fR functions are useful for dealing with +errors and interrupts encountered in a low-level subroutine of a program. +.sp +.LP +The \fBsetjmp()\fR function saves its stack environment in \fIenv\fR for later +use by \fBlongjmp()\fR. A normal call to \fBsetjmp()\fR returns zero. +\fBsetjmp()\fR also saves the register environment. If a \fBlongjmp()\fR call +will be made, the routine which called \fBsetjmp()\fR should not return until +after the \fBlongjmp()\fR has returned control (see below). +.sp +.LP +The \fBlongjmp()\fR function restores the environment saved by the last call of +\fBsetjmp()\fR, and then returns in such a way that execution continues as if +the call of \fBsetjmp()\fR had just returned the value \fIval\fR to the +function that invoked \fBsetjmp()\fR; however, if \fIval\fR were zero, +execution would continue as if the call of \fBsetjmp()\fR had returned one. +This ensures that a ``return'' from \fBsetjmp()\fR caused by a call to +\fBlongjmp()\fR can be distinguished from a regular return from \fBsetjmp()\fR. +The calling function must not itself have returned in the interim, otherwise +\fBlongjmp()\fR will be returning control to a possibly nonexistent +environment. All memory-bound data have values as of the time \fBlongjmp()\fR +was called. The \fBCPU\fR and floating-point data registers are restored to +the values they had at the time that \fBsetjmp()\fR was called. But, because +the \fBregister\fR storage class is only a hint to the C compiler, variables +declared as \fBregister\fR variables may not necessarily be assigned to machine +registers, so their values are unpredictable after a \fBlongjmp()\fR. This is +especially a problem for programmers trying to write machine-independent C +routines. +.sp +.LP +The \fBsetjmp()\fR and \fBlongjmp()\fR functions save and restore the signal +mask while \fB_setjmp()\fR and \fB_longjmp()\fR manipulate only the C stack and +registers. +.sp +.LP +None of these functions save or restore any floating-point status or control +registers. +.SH EXAMPLES +.LP +\fBExample 1 \fRExamples of \fBsetjmp()\fR and \fBlongjmp()\fR. +.sp +.LP +The following example uses both \fBsetjmp()\fR and \fBlongjmp()\fR to return +the flow of control to the appropriate instruction block: + +.sp +.in +2 +.nf +#include <stdio.h> +#include <setjmp.h> +#include <signal.h> +#include <unistd.h> +jmp_buf env; static void signal_handler(); +main(\|) { + int returned_from_longjump, processing = 1; + unsigned int time_interval = 4; + if ((returned_from_longjump = setjmp(env)) != 0) + switch (returned_from_longjump) { + case SIGINT: + printf("longjumped from interrupt %d\en",SIGINT); + break; + case SIGALRM: + printf("longjumped from alarm %d\en",SIGALRM); + break; + } + (void) signal(SIGINT, signal_handler); + (void) signal(SIGALRM, signal_handler); + alarm(time_interval); + while (processing) { + printf(" waiting for you to INTERRUPT (cntrl-C) ...\en"); + sleep(1); + } /* end while forever loop */ +} + +static void signal_handler(sig) +int sig; { + switch (sig) { + case SIGINT: ... /* process for interrupt */ + longjmp(env,sig); + /* break never reached */ + case SIGALRM: ... /* process for alarm */ + longjmp(env,sig); + /* break never reached */ + default: exit(sig); + } +} +.fi +.in -2 + +.sp +.LP +When this example is compiled and executed, and the user sends an interrupt +signal, the output will be: + +.sp +.in +2 +.nf +longjumped from interrupt +.fi +.in -2 + +.sp +.LP +Additionally, every 4 seconds the alarm will expire, signalling this process, +and the output will be: + +.sp +.in +2 +.nf +longjumped from alarm +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBsigvec\fR(3UCB), \fBsetjmp\fR(3C), \fBsignal\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.SH BUGS +.sp +.LP +The \fBsetjmp()\fR function does not save the current notion of whether the +process is executing on the signal stack. The result is that a \fBlongjmp()\fR +to some place on the signal stack leaves the signal stack state incorrect. +.sp +.LP +On some systems \fBsetjmp()\fR also saves the register environment. Therefore, +all data that are bound to registers are restored to the values they had at the +time that \fBsetjmp()\fR was called. All memory-bound data have values as of +the time \fBlongjmp()\fR was called. However, because the \fBregister\fR +storage class is only a hint to the C compiler, variables declared as +\fBregister\fR variables may not necessarily be assigned to machine registers, +so their values are unpredictable after a \fBlongjmp()\fR. When using compiler +options that specify automatic register allocation, the compiler will not +attempt to assign variables to registers in routines that call \fBsetjmp()\fR. +.sp +.LP +The \fBlongjmp()\fR function never causes \fBsetjmp()\fR to return 0, so +programmers should not depend on \fBlongjmp()\fR being able to cause +\fBsetjmp()\fR to return 0. diff --git a/usr/src/man/man3ucb/sigblock.3ucb b/usr/src/man/man3ucb/sigblock.3ucb new file mode 100644 index 0000000000..41b93589bd --- /dev/null +++ b/usr/src/man/man3ucb/sigblock.3ucb @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH sigblock 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +sigblock, sigmask, sigpause, sigsetmask \- block signals +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <signal.h> + +\fBint\fR \fBsigblock\fR(\fImask\fR) +\fBint\fR \fImask\fR; +.fi + +.LP +.nf +\fBint\fR \fBsigmask\fR(\fIsignum\fR) +\fBint\fR \fIsignum\fR; +.fi + +.LP +.nf +\fBint\fR \fBsigpause\fR(\fImask\fR) +\fBint\fR \fImask\fR; +.fi + +.LP +.nf +\fBint\fR \fBsigsetmask\fR(\fImask\fR) +\fBint\fR \fImask\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBsigblock()\fR adds the signals specified in \fImask\fR to the set of signals +currently being blocked from delivery. Signals are blocked if the appropriate +bit in \fImask\fR is a 1; the macro \fBsigmask\fR is provided to construct the +mask for a given \fIsignum\fR. \fBsigblock()\fR returns the previous mask. The +previous mask may be restored using \fBsigsetmask()\fR. +.sp +.LP +\fBsigpause()\fR assigns \fImask\fR to the set of masked signals and then waits +for a signal to arrive; on return the set of masked signals is restored. +\fImask\fR is usually 0 to indicate that no signals are now to be blocked. +\fBsigpause()\fR always terminates by being interrupted, returning \(mi1 and +setting \fBerrno\fR to \fBEINTR.\fR +.sp +.LP +\fBsigsetmask()\fR sets the current signal mask (those signals that are blocked +from delivery). Signals are blocked if the corresponding bit in \fImask\fR is +a 1; the macro \fBsigmask\fR is provided to construct the mask for a given +\fIsignum\fR. +.sp +.LP +In normal usage, a signal is blocked using \fBsigblock()\fR. To begin a +critical section, variables modified on the occurrence of the signal are +examined to determine that there is no work to be done, and the process pauses +awaiting work by using \fBsigpause()\fR with the mask returned by +\fBsigblock()\fR. +.sp +.LP +It is not possible to block \fBSIGKILL\fR, \fBSIGSTOP\fR, or \fBSIGCONT\fR, +this restriction is silently imposed by the system. +.SH RETURN VALUES +.sp +.LP +\fBsigblock()\fR and \fBsigsetmask()\fR return the previous set of masked +signals. \fBsigpause()\fR returns \(mi1 and sets \fBerrno\fR to \fBEINTR\fR. +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBsigaction\fR(2), \fBsignal\fR(3UCB), \fBsigvec\fR(3UCB) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. diff --git a/usr/src/man/man3ucb/siginterrupt.3ucb b/usr/src/man/man3ucb/siginterrupt.3ucb new file mode 100644 index 0000000000..ffd5f7c09a --- /dev/null +++ b/usr/src/man/man3ucb/siginterrupt.3ucb @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1985 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH siginterrupt 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +siginterrupt \- allow signals to interrupt functions +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... + +\fBint\fR \fBsiginterrupt\fR(\fIsig\fR, \fIflag\fR) +\fBint\fR \fIsig\fR, \fIflag\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBsiginterrupt()\fR is used to change the function restart behavior when a +function is interrupted by the specified signal. If the flag is false +(\fB0\fR), then functions will be restarted if they are interrupted by the +specified signal and no data has been transferred yet. System call restart is +the default behavior when the \fBsignal\fR(3C) routine is used. +.sp +.LP +If the flag is true, (\fB1\fR), then restarting of functions is disabled. If +a function is interrupted by the specified signal and no data has been +transferred, the function will return \fB\(mi1\fR with \fBerrno\fR set to +\fBEINTR\fR. Interrupted functions that have started transferring data will +return the amount of data actually transferred. +.sp +.LP +Issuing a \fBsiginterrupt()\fR call during the execution of a signal handler +will cause the new action to take place on the next signal to be caught. +.SH RETURN VALUES +.sp +.LP +A \fB0\fR value indicates that the call succeeded. A \fB\(mi1\fR value +indicates that the call failed and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +\fBsiginterrupt()\fR may return the following error: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIsig\fR is not a valid signal. +.RE + +.SH SEE ALSO +.sp +.LP +\fBsigblock\fR(3UCB), \fBsigvec\fR(3UCB), \fBsignal\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-threaded applications is unsupported. +.sp +.LP +This library routine uses an extension of the \fBsigvec\fR(3UCB) function that +is not available in 4.2 BSD, hence it should not be used if backward +compatibility is needed. diff --git a/usr/src/man/man3ucb/signal.3ucb b/usr/src/man/man3ucb/signal.3ucb new file mode 100644 index 0000000000..20e5376a4a --- /dev/null +++ b/usr/src/man/man3ucb/signal.3ucb @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH signal 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +signal \- simplified software signal facilities +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <signal.h> + +\fBvoid\fR (\fB*signal(\fR\fIsig\fR, \fIfunc\fR))() +\fBint\fR \fIsig\fR; +\fBvoid\fR (\fB*\fR\fIfunc\fR)(); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBsignal()\fR is a simplified interface to the more general \fBsigvec\fR(3UCB) +facility. Programs that use \fBsignal()\fR in preference to \fBsigvec()\fR are +more likely to be portable to all systems. +.sp +.LP +A signal is generated by some abnormal event, initiated by a user at a terminal +(quit, interrupt, stop), by a program error (bus error, etc.), by request of +another program (kill), or when a process is stopped because it wishes to +access its control terminal while in the background (see \fBtermio\fR(7I)). +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. Most signals cause termination of the receiving process 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. +Except for the \fBSIGKILL\fR and \fBSIGSTOP\fR signals, the \fBsignal()\fR call +allows signals either to be ignored or to interrupt to a specified location. +See \fBsigvec\fR(3UCB) for a complete list of the signals. +.sp +.LP +If \fIfunc\fR is \fBSIG_DFL\fR, the default action for signal \fIsig\fR is +reinstated; this default is termination (with a core image for starred signals) +except for signals marked with \(bu or a dagger. Signals marked with \(bu are +discarded if the action is \fBSIG_DFL\fR; signals marked with a dagger cause +the process to stop. If \fIfunc\fR is \fBSIG_IGN\fR the signal is subsequently +ignored and pending instances of the signal are discarded. Otherwise, when the +signal occurs further occurrences of the signal are automatically blocked and +\fIfunc\fR is called. +.sp +.LP +A return from the function unblocks the handled signal and continues the +process at the point it was interrupted. +.sp +.LP +If a caught signal occurs during certain functions, terminating the call +prematurely, the call is automatically restarted. In particular this can occur +during a \fBread\fR(2) or \fBwrite\fR(2) on a slow device (such as a terminal; +but not a file) and during a \fBwait\fR(3C). +.sp +.LP +The value of \fBsignal()\fR is the previous (or initial) value of \fIfunc\fR +for the particular signal. +.sp +.LP +After a \fBfork\fR(2) or \fBvfork\fR(2) the child inherits all signals. An +\fBexec\fR(2) resets all caught signals to the default action; ignored signals +remain ignored. +.SH RETURN VALUES +.sp +.LP +The previous action is returned on a successful call. Otherwise,\fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +\fBsignal()\fR will fail and no action will take place if the following occurs: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIsig\fR is not a valid signal number, or is \fBSIGKILL\fR or \fBSIGSTOP\fR. +.RE + +.SH SEE ALSO +.sp +.LP +\fBkill\fR(1), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), +\fBgetitimer\fR(2), \fBgetrlimit\fR(2), \fBkill\fR(2), \fBread\fR(2), +\fBsigaction\fR(2), \fBwrite\fR(2), \fBabort\fR(3C), \fBptrace\fR(3C), +\fBsetjmp\fR(3C), \fBsetjmp\fR(3UCB), \fBsigblock\fR(3UCB), \fBsignal\fR(3C), +\fBsignal.h\fR(3HEAD), \fBsigstack\fR(3UCB), \fBsigvec\fR(3UCB), +\fBwait\fR(3C), \fBwait\fR(3UCB), \fBtermio\fR(7I) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-threaded applications is unsupported. +.sp +.LP +The handler routine \fIfunc\fR can be declared: +.sp +.in +2 +.nf +void handler(signum) int signum; +.fi +.in -2 + +.sp +.LP +Here \fIsignum\fR is the signal number. See \fBsigvec\fR(3UCB) for more +information. diff --git a/usr/src/man/man3ucb/sigstack.3ucb b/usr/src/man/man3ucb/sigstack.3ucb new file mode 100644 index 0000000000..0964ca461a --- /dev/null +++ b/usr/src/man/man3ucb/sigstack.3ucb @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH sigstack 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +sigstack \- set and/or get signal stack context +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <signal.h> + +\fBint\fR \fBsigstack\fR(\fInss\fR, \fIoss\fR) +\fBstruct sigstack *\fR\fInss\fR, \fB*\fR\fIoss\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsigstack()\fR function allows users to define an alternate stack, called +the "signal stack", on which signals are to be processed. When a signal's +action indicates its handler should execute on the signal stack (specified with +a \fBsigvec\fR(3UCB) call), the system checks to see if the process is +currently executing on that stack. If the process is not currently executing +on the signal stack, the system arranges a switch to the signal stack for the +duration of the signal handler's execution. +.sp +.LP +A signal stack is specified by a \fBsigstack()\fR structure, which includes the +following members: +.sp +.in +2 +.nf +char *ss_sp; /* signal stack pointer */ +int ss_onstack; /* current status */ +.fi +.in -2 + +.sp +.LP +The \fBss_sp\fR member is the initial value to be assigned to the stack pointer +when the system switches the process to the signal stack. Note that, on +machines where the stack grows downwards in memory, this is \fInot\fR the +address of the beginning of the signal stack area. The \fBss_onstack\fR member +is zero or non-zero depending on whether the process is currently executing on +the signal stack or not. +.sp +.LP +If \fInss\fR is not a null pointer, \fBsigstack()\fR sets the signal stack +state to the value in the \fBsigstack()\fR structure pointed to by \fInss\fR. +If \fInss\fR is a \fBnull\fR pointer, the signal stack state will be unchanged. +If \fIoss\fR is not a \fBnull\fR pointer, the current signal stack state is +stored in the \fBsigstack()\fR structure pointed to by \fIoss\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsigstack()\fR function will fail and the signal stack context will +remain unchanged if one of the following occurs. +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +Either \fInss\fR or \fIoss\fR points to memory that is not a valid part of the +process address space. +.RE + +.SH SEE ALSO +.sp +.LP +\fBsigaltstack\fR(2), \fBsigvec\fR(3UCB), \fBsignal\fR(3C) +.SH WARNINGS +.sp +.LP +Signal stacks are not "grown" automatically, as is done for the normal stack. +If the stack overflows unpredictable results may occur. +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-threaded applications is unsupported. diff --git a/usr/src/man/man3ucb/sigvec.3ucb b/usr/src/man/man3ucb/sigvec.3ucb new file mode 100644 index 0000000000..1747403d92 --- /dev/null +++ b/usr/src/man/man3ucb/sigvec.3ucb @@ -0,0 +1,578 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH sigvec 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +sigvec \- software signal facilities +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR \&.\|.\|. ] \fIfile\fR\&.\|.\|. +#include <signal.h> + +\fBint\fR \fBsigvec\fR(\fIsig\fR, \fInvec\fR, \fIovec\fR) +\fBint\fR \fIsig\fR; +\fBstruct sigvec *\fR\fInvec\fR, \fB*\fR\fIovec\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The system defines a set of signals that may be delivered to a process. Signal +delivery resembles the occurrence of a hardware interrupt: the signal is +blocked from further occurrence, the current process context is saved, and a +new one is built. A process may specify a \fIhandler\fR to which a signal is +delivered, or specify that a signal is to be \fIblocked\fR or \fIignored\fR. A +process may also specify that a default action is to be taken by the system +when a signal occurs. Normally, signal handlers execute on the current stack of +the process. This may be changed, on a per-handler basis, so that signals are +taken on a special \fIsignal stack\fR. +.sp +.LP +All signals have the same \fIpriority\fR. Signal routines execute with the +signal that caused their invocation to be \fIblocked\fR, but other signals may +yet occur. A global \fIsignal mask\fR defines the set of signals currently +blocked from delivery to a process. The signal mask for a process is +initialized from that of its parent (normally 0). It may be changed with a +\fBsigblock()\fR or \fBsigsetmask()\fR call, or when a signal is delivered to +the process. +.sp +.LP +A process may also specify a set of \fIflags\fR for a signal that affect the +delivery of that signal. +.sp +.LP +When a signal condition arises for a process, the signal is added to a set of +signals pending for the process. If the signal is not currently \fIblocked\fR +by the process then it is delivered to the process. When a signal is +delivered, the current state of the process is saved, a new signal mask is +calculated (as described below), and the signal handler is invoked. The call to +the handler is arranged so that if the signal handling routine returns normally +the process will resume execution in the context from before the signal's +delivery. If the process wishes to resume in a different context, then it must +arrange to restore the previous context itself. +.sp +.LP +When a signal is delivered to a process a new signal mask is installed for the +duration of the process' signal handler (or until a \fBsigblock()\fR or +\fBsigsetmask()\fR call is made). This mask is formed by taking the current +signal mask, adding the signal to be delivered, and \fBOR\fRing in the signal +mask associated with the handler to be invoked. +.sp +.LP +The action to be taken when the signal is delivered is specified by a +\fBsigvec()\fR structure, which includes the following members: +.sp +.in +2 +.nf +void (*sv_handler)(\|); /* signal handler */ +int sv_mask; /* signal mask to apply */ +int sv_flags; /* see signal options */ +#define SV_ONSTACK /* take signal on signal stack */ +#define SV_INTERRUPT /* do not restart system on signal + return */ +#define SV_RESETHAND /* reset handler to SIG_DFL when + signal taken*/ +.fi +.in -2 + +.sp +.LP +If the \fBSV_ONSTACK\fR bit is set in the flags for that signal, the system +will deliver the signal to the process on the signal stack specified with +\fBsigstack\fR(3UCB) rather than delivering the signal on the current stack. +.sp +.LP +If \fInvec\fR is not a \fINULL\fR pointer, \fBsigvec()\fR assigns the handler +specified by \fBsv_handler()\fR, the mask specified by \fBsv_mask()\fR, and the +flags specified by \fBsv_flags()\fR to the specified signal. If \fInvec\fR is +a \fINULL\fR pointer, \fBsigvec()\fR does not change the handler, mask, or +flags for the specified signal. +.sp +.LP +The mask specified in \fInvec\fR is not allowed to block \fBSIGKILL\fR, +\fBSIGSTOP\fR, or \fBSIGCONT\fR. The system enforces this restriction silently. +.sp +.LP +If \fIovec\fR is not a \fINULL\fR pointer, the handler, mask, and flags in +effect for the signal before the call to \fBsigvec()\fR are returned to the +user. A call to \fBsigvec()\fR with \fInvec\fR a \fINULL\fR pointer and +\fIovec\fR not a \fINULL\fR pointer can be used to determine the handling +information currently in effect for a signal without changing that information. +.sp +.LP +The following is a list of all signals with names as in the include file +\fB<signal.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBSIGHUP\fR\fR +.ad +.RS 13n +.rt +hangup +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGINT\fR\fR +.ad +.RS 13n +.rt +interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGQUIT\fR*\fR +.ad +.RS 13n +.rt +quit +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGILL\fR*\fR +.ad +.RS 13n +.rt +illegal instruction +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGTRAP\fR*\fR +.ad +.RS 13n +.rt +trace trap +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGABRT\fR*\fR +.ad +.RS 13n +.rt +abort (generated by \fBabort\fR(3C) routine) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGEMT\fR*\fR +.ad +.RS 13n +.rt +emulator trap +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGFPE\fR*\fR +.ad +.RS 13n +.rt +arithmetic exception +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGKILL\fR\fR +.ad +.RS 13n +.rt +kill (cannot be caught, blocked, or ignored) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGBUS\fR*\fR +.ad +.RS 13n +.rt +bus error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGSEGV\fR*\fR +.ad +.RS 13n +.rt +segmentation violation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGSYS\fR*\fR +.ad +.RS 13n +.rt +bad argument to function +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGPIPE\fR\fR +.ad +.RS 13n +.rt +write on a pipe or other socket with no one to read it +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGALRM\fR\fR +.ad +.RS 13n +.rt +alarm clock +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGTERM\fR\fR +.ad +.RS 13n +.rt +software termination signal +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGURG\fR*\fR +.ad +.RS 13n +.rt +urgent condition present on socket +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGSTOP\fR**\fR +.ad +.RS 13n +.rt +stop (cannot be caught, blocked, or ignored) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGTSTP\fR**\fR +.ad +.RS 13n +.rt +stop signal generated from keyboard +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGCONT\fR*\fR +.ad +.RS 13n +.rt +continue after stop (cannot be blocked) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGCHLD\fR*\fR +.ad +.RS 13n +.rt +child status has changed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGTTIN\fR**\fR +.ad +.RS 13n +.rt +background read attempted from control terminal +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGTTOU\fR**\fR +.ad +.RS 13n +.rt +background write attempted to control terminal +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGIO\fR*\fR +.ad +.RS 13n +.rt +I/O is possible on a descriptor (see \fBfcntl\fR(2)) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGXCPU\fR\fR +.ad +.RS 13n +.rt +cpu time limit exceeded (see \fBgetrlimit\fR(2)) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGXFSZ\fR\fR +.ad +.RS 13n +.rt +file size limit exceeded (see \fBgetrlimit\fR(2)) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGVTALRM\fR\fR +.ad +.RS 13n +.rt +virtual time alarm; see \fBsetitimer()\fR on \fBgetitimer\fR(2) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGPROF\fR\fR +.ad +.RS 13n +.rt +profiling timer alarm; see \fBsetitimer()\fR on \fBgetitimer\fR(2) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGWINCH\fR*\fR +.ad +.RS 13n +.rt +window changed (see \fBtermio\fR(7I)) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGLOST\fR\fR +.ad +.RS 13n +.rt +resource lost (see \fBlockd\fR(1M)) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGUSR1\fR\fR +.ad +.RS 13n +.rt +user-defined signal 1 +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGUSR2\fR\fR +.ad +.RS 13n +.rt +user-defined signal 2 +.RE + +.sp +.LP +The starred signals in the list above cause a core image if not caught or +ignored. +.sp +.LP +Once a signal handler is installed, it remains installed until another +\fBsigvec()\fR call is made, or an \fBexecve\fR(2) is performed, unless the +\fBSV_RESETHAND\fR bit is set in the flags for that signal. In that case, the +value of the handler for the caught signal will be set to \fBSIG_DFL\fR before +entering the signal-catching function, unless the signal is \fBSIGILL\fR, +\fBSIGPWR\fR, or \fBSIGTRAP\fR. Also, if this bit is set, the bit for that +signal in the signal mask will not be set; unless the signal mask associated +with that signal blocks that signal, further occurrences of that signal will +not be blocked. The \fBSV_RESETHAND\fR flag is not available in 4.2BSD, hence +it should not be used if backward compatibility is needed. +.sp +.LP +The default action for a signal may be reinstated by setting the signal's +handler to \fBSIG_DFL\fR; this default is termination except for signals marked +with * or **. Signals marked with * are discarded if the action is +\fBSIG_DFL\fR; signals marked with ** cause the process to stop. If the process +is terminated, a "core image" will be made in the current working directory of +the receiving process if the signal is one for which an asterisk appears in the +above list (see \fBcore\fR(4)). +.sp +.LP +If the handler for that signal is \fBSIG_IGN\fR, the signal is subsequently +ignored, and pending instances of the signal are discarded. +.sp +.LP +If a caught signal occurs during certain functions, the call is normally +restarted. The call can be forced to terminate prematurely with an \fBEINTR\fR +error return by setting the \fBSV_INTERRUPT\fR bit in the flags for that +signal. The \fBSV_INTERRUPT\fR flag is not available in 4.2BSD, hence it should +not be used if backward compatibility is needed. The affected functions are +\fBread\fR(2) or \fBwrite\fR(2) on a slow device (such as a terminal or pipe or +other socket, but not a file) and during a \fBwait\fR(3C). +.sp +.LP +After a \fBfork\fR(2) or \fBvfork\fR(2) the child inherits all signals, the +signal mask, the signal stack, and the restart/interrupt and +reset-signal-handler flags. +.sp +.LP +The \fBexecve\fR(2) call resets all caught signals to default action and resets +all signals to be caught on the user stack. Ignored signals remain ignored; the +signal mask remains the same; signals that interrupt functions continue to do +so. +.sp +.LP +The accuracy of \fIaddr\fR is machine dependent. For example, certain machines +may supply an address that is on the same page as the address that caused the +fault. If an appropriate \fIaddr\fR cannot be computed it will be set to +\fBSIG_NOADDR\fR. +.SH RETURN VALUES +.sp +.LP +A \fB0\fR value indicates that the call succeeded. A \fB\(mi1\fR return value +indicates that an error occurred and \fBerrno\fR is set to indicate the reason. +.SH ERRORS +.sp +.LP +\fBsigvec()\fR will fail and no new signal handler will be installed if one of +the following occurs: +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +Either \fInvec\fR or \fIovec\fR is not a \fINULL\fR pointer and points to +memory that is not a valid part of the process address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +\fIsig\fR is not a valid signal number or is \fBSIGKILL\fR or \fBSIGSTOP\fR. +.RE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), +\fBgetitimer\fR(2), \fBgetrlimit\fR(2), \fBioctl\fR(2), \fBkill\fR(2), +\fBread\fR(2), \fBumask\fR(2), \fBvfork\fR(2), \fBwrite\fR(2), +\fBptrace\fR(3C), \fBsetjmp\fR(3C) \fBsigblock\fR(3UCB), \fBsignal\fR(3C), +\fBsignal\fR(3UCB), \fBsigstack\fR(3UCB), \fBwait\fR(3C), \fBwait\fR(3UCB), +\fBcore\fR(4), \fBstreamio\fR(7I), \fBtermio\fR(7I) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +\fBSIGPOLL\fR is a synonym for \fBSIGIO\fR. A \fBSIGIO\fR will be issued when a +file descriptor corresponding to a \fBSTREAMS\fR (see \fBIntro\fR(2)) file has +a "selectable" event pending. Unless that descriptor has been put into +asynchronous mode (see \fBfcntl\fR(2)), a process may specifically request that +this signal be sent using the \fBI_SETSIG\fR \fBioctl\fR(2) call (see +\fBstreamio\fR(7I)). Otherwise, the process will never receive \fBSIGPOLLs0\fR. +.sp +.LP +The handler routine can be declared: +.sp +.in +2 +.nf +void handler(int sig, int code, struct sigcontext *scp, + char *addr); +.fi +.in -2 + +.sp +.LP +Here \fIsig\fR is the signal number; \fIcode\fR is a parameter of certain +signals that provides additional detail; \fIscp\fR is a pointer to the +\fBsigcontext\fR structure (defined in \fBsignal.h\fR), used to restore the +context from before the signal; and \fIaddr\fR is additional address +information. +.sp +.LP +The signals \fBSIGKILL\fR, \fBSIGSTOP\fR, and \fBSIGCONT\fR cannot be ignored. diff --git a/usr/src/man/man3ucb/sleep.3ucb b/usr/src/man/man3ucb/sleep.3ucb new file mode 100644 index 0000000000..072387b25c --- /dev/null +++ b/usr/src/man/man3ucb/sleep.3ucb @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH sleep 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +sleep \- suspend execution for interval +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... + +\fBint\fR \fBsleep\fR(\fIseconds\fR) +\fBunsigned\fR \fIseconds\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBsleep()\fR suspends the current process from execution for the number of +seconds specified by the argument. The actual suspension time may be up to 1 +second less than that requested, because scheduled wakeups occur at fixed +1-second intervals, and may be an arbitrary amount longer because of other +activity in the system. +.sp +.LP +\fBsleep()\fR is implemented by setting an interval timer and pausing until it +expires. The previous state of this timer is saved and restored. If the sleep +time exceeds the time to the expiration of the previous value of the timer, the +process sleeps only until the timer would have expired, and the signal which +occurs with the expiration of the timer is sent one second later. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelAsync-Signal-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBalarm\fR(2), \fBgetitimer\fR(2), \fBlongjmp\fR(3C), \fBsiglongjmp\fR(3C), +\fBsleep\fR(3C), \fBusleep\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +\fBSIGALRM\fR should \fInot\fR be blocked or ignored during a call to +\fBsleep()\fR. Only a prior call to \fBalarm\fR(2) should generate +\fBSIGALRM\fR for the calling process during a call to \fBsleep()\fR. A +signal-catching function should \fInot\fR interrupt a call to \fBsleep()\fR to +call \fBsiglongjmp\fR(3C) or \fBlongjmp\fR(3C) to restore an environment saved +prior to the \fBsleep()\fR call. +.SH WARNINGS +.sp +.LP +\fBsleep()\fR is slightly incompatible with \fBalarm\fR(2). Programs that do +not execute for at least one second of clock time between successive calls to +\fBsleep()\fR indefinitely delay the alarm signal. Use \fBsleep\fR(3C). Each +\fBsleep\fR(3C) call postpones the alarm signal that would have been sent +during the requested sleep period to occur one second later. diff --git a/usr/src/man/man3ucb/syscall.3ucb b/usr/src/man/man3ucb/syscall.3ucb new file mode 100644 index 0000000000..e936521f3d --- /dev/null +++ b/usr/src/man/man3ucb/syscall.3ucb @@ -0,0 +1,52 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH syscall 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +syscall \- indirect system call +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/syscall.h> + +\fBint\fR \fBsyscall\fR(\fInumber\fR, \fIarg\fR, \fI\&...\fR) +\fBint\fR \fInumber\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +\fBsyscall()\fR performs the function whose assembly language interface has the +specified \fInumber\fR, and arguments \fIarg .\|.\|.\fR. Symbolic constants for +functions can be found in the header \fB<sys/syscall.h>\fR. +.SH RETURN VALUES +.sp +.LP +On error \fBsyscall()\fR returns \(mi1 and sets the external variable +\fBerrno\fR (see \fBIntro\fR(2)). +.SH FILES +.sp +.LP +\fB<sys/syscall.h>\fR +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBpipe\fR(2) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.SH WARNINGS +.sp +.LP +There is no way to use \fBsyscall()\fR to call functions such as \fBpipe\fR(2) +which return values that do not fit into one hardware register. +.sp +.LP +Since many system calls are implemented as library wrappers around traps to the +kernel, these calls may not behave as documented when called from +\fBsyscall()\fR, which bypasses these wrappers. For these reasons, using +\fBsyscall()\fR is not recommended. diff --git a/usr/src/man/man3ucb/times.3ucb b/usr/src/man/man3ucb/times.3ucb new file mode 100644 index 0000000000..8d98707ee5 --- /dev/null +++ b/usr/src/man/man3ucb/times.3ucb @@ -0,0 +1,62 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH times 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +times \- get process times +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/param.h> +#include <sys/types.h> +#include <sys/times.h> + +\fBint\fR \fBtimes\fR(\fItmsp\fR) +\fIregister struct tms *\fR\fItmsp\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBtimes()\fR function returns time-accounting information for the current +process and for the terminated child processes of the current process. All +times are reported in clock ticks. The number of clock ticks per second is +defined by the variable \fBCLK_TCK\fR, found in the header \fB<limits.h>\fR. +.sp +.LP +A structure with the following members is returned by \fBtimes()\fR: +.sp +.in +2 +.nf +time_t tms_utime; /* user time */ +time_t tms_stime; /* system time */ +time_t tms_cutime; /* user time, children */ +time_t tms_cstime; /* system time, children */ +.fi +.in -2 + +.sp +.LP +The children's times are the sum of the children's process times and their +children's times. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBtimes()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR\&. +.SH SEE ALSO +.sp +.LP +\fBtime\fR(1), \fBtime\fR(2), \fBgetrusage\fR(3C), \fBwait\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-threaded applications is unsupported. +.sp +.LP +The \fBtimes()\fR function has been superseded by \fBgetrusage\fR(3C). diff --git a/usr/src/man/man3ucb/wait.3ucb b/usr/src/man/man3ucb/wait.3ucb new file mode 100644 index 0000000000..a685d47b69 --- /dev/null +++ b/usr/src/man/man3ucb/wait.3ucb @@ -0,0 +1,383 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright (c) 1980 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH wait 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions" +.SH NAME +wait, wait3, wait4, waitpid, WIFSTOPPED, WIFSIGNALED, WIFEXITED \- wait for +process to terminate or stop +.SH SYNOPSIS +.LP +.nf +\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ... +#include <sys/wait.h> + +\fBint\fR \fBwait\fR(\fIstatusp\fR) +\fBint *\fR\fIstatusp\fR; +.fi + +.LP +.nf +\fBint\fR \fBwaitpid\fR(\fIpid\fR, \fIstatusp\fR, \fIoptions\fR) +\fBint\fR \fIpid\fR; +\fBint *\fR\fIstatusp\fR; +\fBint\fR \fIoptions\fR; +.fi + +.LP +.nf +#include <sys/time.h> +#include <sys/resource.h> + +\fBint\fR \fBwait3\fR(\fIstatusp\fR, \fIoptions\fR, \fIrusage\fR) +\fBint *\fR\fIstatusp\fR; +\fBint\fR \fIoptions\fR; +\fBstruct rusage *\fR\fIrusage\fR; +.fi + +.LP +.nf +\fBint\fR \fBwait4\fR(\fIpid\fR, \fIstatusp\fR, \fIoptions\fR, \fIrusage\fR) +\fBint\fR \fIpid\fR; +\fBint *\fR\fIstatusp\fR; +\fBint\fR \fIoptions\fR; +\fBstruct rusage *\fR\fIrusage\fR; +.fi + +.LP +.nf +\fBWIFSTOPPED\fR(\fIstatus\fR) +\fBint\fR \fIstatus\fR; +.fi + +.LP +.nf +\fBWIFSIGNALED\fR(\fIstatus\fR) +\fBint\fR \fIstatus\fR; +.fi + +.LP +.nf +\fBWIFEXITED\fR(\fIstatus\fR) +\fBint\fR \fIstatus\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBwait()\fR function delays its caller until a signal is received or one +of its child processes terminates or stops due to tracing. If any child process +has died or stopped due to tracing and this has not been reported using +\fBwait()\fR, return is immediate, returning the process \fBID\fR and exit +status of one of those children. If that child process has died, it is +discarded. If there are no children, return is immediate with the value \(mi1 +returned. If there are only running or stopped but reported children, the +calling process is blocked. +.sp +.LP +If \fIstatus\fR is not a \fINULL\fR pointer, then on return from a successful +\fBwait()\fR call the status of the child process whose process \fBID\fR is the +return value of \fBwait()\fR is stored in the \fBwait()\fR union pointed to by +\fIstatus\fR. The \fBw_status\fR member of that union is an \fBint\fR; it +indicates the cause of termination and other information about the terminated +process in the following manner: +.RS +4 +.TP +.ie t \(bu +.el o +If the low-order 8 bits of \fBw_status\fR are equal to 0177, the child process +has stopped; the 8 bits higher up from the low-order 8 bits of \fBw_status\fR +contain the number of the signal that caused the process to stop. +See\fBptrace\fR(3C) and \fBsigvec\fR(3UCB). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the low-order 8 bits of \fBw_status\fR are non-zero and are not equal to +0177, the child process terminated due to a signal; the low-order 7 bits of +\fBw_status\fR contain the number of the signal that terminated the process. In +addition, if the low-order seventh bit of \fBw_status\fR (that is, bit 0200) is +set, a ``core image'' of the process was produced; see \fBsigvec\fR(3UCB). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Otherwise, the child process terminated due to an \fBexit()\fR call; the 8 bits +higher up from the low-order 8 bits of \fBw_status\fR contain the low-order 8 +bits of the argument that the child process passed to \fBexit()\fR; see +\fBexit\fR(2). +.RE +.sp +.LP +\fBwaitpid()\fR behaves identically to \fBwait()\fR if \fIpid\fR has a value +of \(mi1 and \fIoptions\fR has a value of zero. Otherwise, the behavior of +\fBwaitpid()\fR is modified by the values of \fIpid\fR and \fIoptions\fR as +follows: +.sp +.LP +\fIpid\fR specifies a set of child processes for which status is requested. +\fBwaitpid()\fR only returns the status of a child process from this set. +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is equal to \(mi1, status is requested for any child process. In +this respect, \fBwaitpid()\fR is then equivalent to \fBwait()\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is greater than zero, it specifies the process \fBID\fR of a +single child process for which status is requested. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is equal to zero, status is requested for any child process whose +process group \fBID\fR is equal to that of the calling process. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIpid\fR is less than \(mi1, status is requested for any child process +whose process group \fBID\fR is equal to the absolute value of \fIpid\fR. +.RE +.sp +.LP +\fIoptions\fR is constructed from the bitwise inclusive \fBOR\fR of zero or +more of the following flags, defined in the header \fB<sys/wait.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBWNOHANG\fR\fR +.ad +.RS 13n +.rt +\fBwaitpid()\fR does not suspend execution of the calling process if status is +not immediately available for one of the child processes specified by +\fIpid\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWUNTRACED\fR\fR +.ad +.RS 13n +.rt +The status of any child processes specified by \fIpid\fR that are stopped, and +whose status has not yet been reported since they stopped, are also reported to +the requesting process. +.RE + +.sp +.LP +\fBwait3()\fR is an alternate interface that allows both non-blocking status +collection and the collection of the status of children stopped by any means. +The \fIstatus\fR parameter is defined as above. The \fIoptions\fR parameter is +used to indicate the call should not block if there are no processes that have +status to report (\fBWNOHANG\fR), and/or that children of the current process +that are stopped due to a \fBSIGTTIN\fR, \fBSIGTTOU\fR, \fBSIGTSTP\fR, or +\fBSIGSTOP\fR signal are eligible to have their status reported as well +(\fBWUNTRACED\fR). A terminated child is discarded after it reports status, and +a stopped process will not report its status more than once. If \fIrusage\fR is +not a \fINULL\fR pointer, a summary of the resources used by the terminated +process and all its children is returned. Only the user time used and the +system time used are currently available. They are returned in +\fBrusage.ru_utime\fR and \fBrusage.ru_stime\fR, respectively. +.sp +.LP +When the \fBWNOHANG\fR option is specified and no processes have status to +report, \fBwait3()\fR returns 0. The \fBWNOHANG\fR and \fBWUNTRACED\fR options +may be combined by \fBORing\fR the two values. +.sp +.LP +\fBwait4()\fR is another alternate interface. With a \fIpid\fR argument of 0, +it is equivalent to \fBwait3()\fR. If \fIpid\fR has a nonzero value, then +\fBwait4()\fR returns status only for the indicated process \fBID,\fR but not +for any other child processes. +.sp +.LP +\fBWIFSTOPPED\fR, \fBWIFSIGNALED\fR, \fBWIFEXITED\fR, are macros that take an +argument \fIstatus\fR, of type \fBint\fR, as returned by \fBwait()\fR, or +\fBwait3()\fR, or \fBwait4()\fR. \fBWIFSTOPPED\fR evaluates to true (1) when +the process for which the \fBwait()\fR call was made is stopped, or to false +(0) otherwise. \fBWIFSIGNALED\fR evaluates to true when the process was +terminated with a signal. \fBWIFEXITED\fR evaluates to true when the process +exited by using an \fBexit\fR(2) call. +.SH RETURN VALUES +.sp +.LP +If \fBwait()\fRor \fBwaitpid()\fR 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 \fB\(mi1\fR is returned and \fBerrno\fR is set to +indicate the error. +.sp +.LP +If \fBwait()\fR or \fBwaitpid()\fR return due to the delivery of a signal to +the calling process, a value of \fB\(mi1\fR is returned and \fBerrno\fR is set +to \fBEINTR.\fR If \fBwaitpid()\fR function was invoked with \fBWNOHANG\fR set +in \fIoptions\fR, it has at least one child process specified by \fIpid\fR for +which status is not available, and status is not available for any process +specified by \fIpid\fR, a value of zero is returned. Otherwise, a value of +\fB\(mi1\fR is returned, and \fBerrno\fR is set to indicate the error. +.sp +.LP +\fBwait3(\|)\fR and \fBwait4(\|)\fR return 0 if \fBWNOHANG\fR is specified and +there are no stopped or exited children, and returns the process \fBID\fR of +the child process if it returns due to a stopped or terminated child process. +Otherwise, they returns a value of \fB\(mi1\fR and sets \fBerrno\fR to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBwait()\fR, \fBwait3()\fR and \fBwait4()\fR functions will fail and +return immediately if: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The calling process has no existing unwaited-for child processes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +The \fIstatus\fR or \fIrusage\fR arguments point to an illegal address. +.RE + +.sp +.LP +\fBwaitpid()\fR may set \fBerrno\fR to: +.sp +.ne 2 +.mk +.na +\fB\fBECHILD\fR\fR +.ad +.RS 10n +.rt +The process or process group specified by \fIpid\fR does not exist or is not a +child of the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 10n +.rt +The function was interrupted by a signal. The value of the location pointed to +by \fIstatusp\fR is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value of \fIoptions\fR is not valid. +.RE + +.sp +.LP +The \fBwait()\fR, \fBwait3()\fR, and \fBwait4()\fR functions will terminate +prematurely, return \(mi1, and set \fBerrno\fR to \fBEINTR\fR upon the arrival +of a signal whose \fBSV_INTERRUPT\fR bit in its flags field is set (see +\fBsigvec\fR(3UCB) and \fBsiginterrupt\fR(3UCB)). \fBsignal\fR(3UCB), sets this +bit for any signal it catches. +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBgetrusage\fR(3C), \fBptrace\fR(3C), \fBsiginterrupt\fR(3UCB), +\fBsignal\fR(3C), \fBsignal\fR(3UCB), \fBsigvec\fR(3UCB), \fBwait\fR(3C), +\fBwaitpid\fR(3C) +.SH NOTES +.sp +.LP +Use of these interfaces should be restricted to only applications written on +BSD platforms. Use of these interfaces with any of the system libraries or in +multi-thread applications is unsupported. +.sp +.LP +If a parent process terminates without waiting on its children, the +initialization process (process \fBID\fR = 1) inherits the children. +.sp +.LP +The \fBwait()\fR, \fBwait3()\fR, and \fBwait4()\fR functions are automatically +restarted when a process receives a signal while awaiting termination of a +child process, unless the \fBSV_INTERRUPT\fR bit is set in the flags for that +signal. +.sp +.LP +Calls to \fBwait()\fR with an argument of \fB0\fR should be cast to type +`\fBint *\fR', as in: +.sp +.in +2 +.nf +\fBwait((int *)0)\fR +.fi +.in -2 +.sp + +.sp +.LP +Previous SunOS releases used \fBunion\fR \fBwait\fR\fB*statusp\fR and +\fBunion\fR \fBwait\fR \fBstatus\fR in place of \fBint *statusp\fR and +\fBint\fR status. The union contained a member \fBw_status\fR that could be +treated in the same way as \fIstatus\fR. +.sp +.LP +Other members of the \fBwait\fR union could be used to extract this information +more conveniently: +.RS +4 +.TP +.ie t \(bu +.el o +If the \fBw_stopval\fR member had the value \fB\fR\fBWSTOPPED\fR\fB, \fR the +child process had stopped; the value of the \fBw_stopsig\fR member was the +signal that stopped the process. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the \fBw_termsig\fR member was non-zero, the child process terminated due to +a signal; the value of the \fBw_termsig\fR member was the number of the signal +that terminated the process. If the \fBw_coredump\fR member was non-zero, a +core dump was produced. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Otherwise, the child process terminated due to a call to \fBexit()\fR. The +value of the \fBw_retcode\fR member was the low-order 8 bits of the argument +that the child process passed to \fBexit()\fR. +.RE +.sp +.LP +\fBunion\fR \fBwait\fR is obsolete in light of the new specifications provided +by \fIIEEE Std 1003.1-1988\fR and endorsed by \fISVID89\fR and \fIXPG3\fR. +SunOS Release 4.1 supports \fBunion\fR\fBwait\fR for backward compatibility, +but it will disappear in a future release. |